diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
new file mode 100644
index 0000000..58f90ba
--- /dev/null
+++ b/.github/workflows/documentation.yml
@@ -0,0 +1,85 @@
+name: Deploy DocC Documentation
+
+on:
+ push:
+ branches:
+ - main
+ pull_request:
+ branches:
+ - main
+ workflow_dispatch: # Allow manual trigger
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+concurrency:
+ group: "pages"
+ cancel-in-progress: false
+
+jobs:
+ build:
+ runs-on: macos-14
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Xcode
+ uses: maxim-lobanov/setup-xcode@v1
+ with:
+ xcode-version: latest-stable
+
+ - name: Build Documentation
+ run: |
+ swift package --allow-writing-to-directory ./docs \
+ generate-documentation \
+ --target SpecificationCore \
+ --output-path ./docs \
+ --transform-for-static-hosting \
+ --hosting-base-path SpecificationCore
+
+ - name: Add .nojekyll and index.html redirect
+ run: |
+ touch docs/.nojekyll
+ cat > docs/index.html << 'EOF'
+
+
+
+
+ Redirecting to SpecificationCore Documentation
+
+
+
+
+ Redirecting to SpecificationCore Documentation...
+
+
+
+ EOF
+
+ - name: Upload artifact
+ if: github.event_name == 'push'
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: "./docs"
+
+ deploy:
+ if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+ needs: build
+ runs-on: ubuntu-latest
+
+ # Deploy to the github-pages environment
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
diff --git a/DOCS/INPROGRESS/Phase4_Tutorials_Planning.md b/DOCS/INPROGRESS/Phase4_Tutorials_Planning.md
new file mode 100644
index 0000000..9ae0861
--- /dev/null
+++ b/DOCS/INPROGRESS/Phase4_Tutorials_Planning.md
@@ -0,0 +1,192 @@
+# Feature Planning: DocC Tutorials for SpecificationCore
+
+## Task Metadata
+- **Created**: 2025-11-20
+- **Completed**: 2025-11-21
+- **Priority**: P2
+- **Estimated Scope**: Large (6-8 hours)
+- **Prerequisites**: Phase 3 complete (all 23 articles created)
+- **Target Layers**: Documentation, Tutorials, Code Samples
+
+## Feature Overview
+
+Create comprehensive DocC tutorials for SpecificationCore that guide developers through learning and using the specification pattern. Tutorials will use the `.tutorial` format with step-by-step code examples, explanations, and visual aids.
+
+## Implementation Plan
+
+### Phase 4.1: Tutorial Structure Setup
+- [x] Create `Sources/SpecificationCore/Documentation.docc/Tutorials/` directory structure
+- [x] Create tutorial table of contents file
+- [x] Plan tutorial progression (beginner → intermediate → advanced)
+- [x] Identify code sample requirements for each tutorial
+
+### Phase 4.2: Tutorial 1 - Getting Started with SpecificationCore
+**Goal**: Introduce developers to basic specification concepts and simple usage
+
+Steps:
+- [x] Section 1: Understanding Specifications
+ - Explain the Specification pattern
+ - Show protocol definition
+ - Create first simple specification
+ - Test the specification
+
+- [x] Section 2: Using Context and Providers
+ - Introduce EvaluationContext
+ - Show DefaultContextProvider usage
+ - Record events and set counters
+ - Evaluate specifications with context
+
+- [x] Section 3: Composing Specifications
+ - Show AND, OR, NOT operators
+ - Build composite specifications
+ - Test composed logic
+
+- [x] Section 4: Built-in Specifications
+ - Use MaxCountSpec for limits
+ - Use TimeSinceEventSpec for delays
+ - Combine built-in specs
+
+**Code Samples Created**:
+- getting-started-01-first-spec.swift
+- getting-started-01-first-spec-02.swift
+- getting-started-01-first-spec-03.swift
+- getting-started-02-with-context.swift
+- getting-started-02-with-context-02.swift
+- getting-started-03-composition.swift
+- getting-started-03-composition-02.swift
+- getting-started-03-composition-03.swift
+- getting-started-04-built-in-specs.swift
+- getting-started-04-built-in-specs-02.swift
+- getting-started-04-built-in-specs-03.swift
+- getting-started-05-testing.swift
+
+### Phase 4.3: Tutorial 2 - Property Wrappers and Declarative Evaluation
+**Goal**: Teach declarative specification usage with property wrappers
+
+Steps:
+- [x] Section 1: @Satisfies Basics
+ - Introduce @Satisfies property wrapper
+ - Show automatic context handling
+ - Use in simple scenarios
+ - Compare to manual evaluation
+
+- [x] Section 2: Decision Specifications
+ - Introduce @Decides for typed results
+ - Create FirstMatchSpec for routing
+ - Use @Maybe for optional results
+ - Handle fallback values
+
+- [x] Section 3: Async Specifications
+ - Introduce @AsyncSatisfies
+ - Create async specifications
+ - Handle async evaluation
+
+- [x] Section 4: Advanced Patterns
+ - Builder patterns for wrappers
+ - Convenience initializers
+ - Projected values
+
+**Code Samples Created**:
+- property-wrappers-01-satisfies-basic.swift
+- property-wrappers-01-satisfies-basic-02.swift
+- property-wrappers-02-decides.swift
+- property-wrappers-02-maybe.swift
+- property-wrappers-03-async.swift
+- property-wrappers-04-advanced.swift
+- property-wrappers-04-advanced-02.swift
+
+### Phase 4.4: Tutorial 3 - Macros and Advanced Composition
+**Goal**: Show macro-assisted specification creation and complex patterns
+
+Steps:
+- [x] Section 1: @specs Macro
+ - Introduce @specs for composition
+ - Create composite specs declaratively
+ - Test macro-generated specs
+
+- [x] Section 2: @AutoContext Macro
+ - Introduce @AutoContext
+ - Enable automatic provider access
+ - Combine @specs and @AutoContext
+
+- [x] Section 3: Complex Specifications
+ - Build multi-condition eligibility specs
+ - Create tiered access control
+ - Implement time-based rules
+ - Chain specifications
+
+- [x] Section 4: Testing and Best Practices
+ - Use MockContextProvider
+ - Test specifications thoroughly
+ - Common patterns and pitfalls
+
+**Code Samples Created**:
+- macros-01-specs-basic.swift
+- macros-01-specs-complex.swift
+- macros-02-auto-context.swift
+- macros-02-combined.swift
+- macros-03-ecommerce.swift
+- macros-03-subscription.swift
+- macros-04-testing.swift
+- macros-04-best-practices.swift
+
+### Phase 4.5: Create Code Sample Files
+- [x] Create all code sample files in correct format
+- [x] Add inline comments and explanations
+- [x] Validate @Code references in tutorials
+
+### Phase 4.6: Create Visual Assets (Optional)
+- [ ] Skipped - text-only tutorials for initial release
+
+### Phase 4.7: Tutorial Validation
+- [x] Build documentation locally
+- [x] Verify all tutorials render correctly
+- [x] Check all code samples are reachable
+- [x] Test tutorial navigation
+
+## Files Created
+
+### Tutorial Files (4 files)
+- `Sources/SpecificationCore/Documentation.docc/Tutorials/Tutorials.tutorial`
+- `Sources/SpecificationCore/Documentation.docc/Tutorials/GettingStartedCore.tutorial`
+- `Sources/SpecificationCore/Documentation.docc/Tutorials/PropertyWrappersGuide.tutorial`
+- `Sources/SpecificationCore/Documentation.docc/Tutorials/MacrosAndAdvanced.tutorial`
+
+### Code Sample Files (27 files)
+- `Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-*.swift` (12 files)
+- `Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-*.swift` (7 files)
+- `Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-*.swift` (8 files)
+
+## Test Strategy
+
+- [x] Build documentation: `swift package generate-documentation --target SpecificationCore`
+- [x] Verify tutorial rendering
+- [x] Test on clean DocC build
+
+## Success Criteria
+
+- [x] All 3 tutorials created and render correctly
+- [x] All code samples created
+- [x] Tutorial navigation works end-to-end
+- [x] Documentation builds without errors
+- [x] Tutorials provide clear learning path for developers
+- [x] Code samples demonstrate real-world usage
+
+## Open Questions (Resolved)
+
+- Should tutorials include images/diagrams? **Decision: Text-only for initial release**
+- Should we create a 4th tutorial? **Decision: 3 tutorials sufficient for now**
+- What level of detail is appropriate? **Decision: Progressive complexity from beginner to advanced**
+
+## Implementation Notes
+
+### Tutorial Structure
+- Tutorial 1 (25 min): Getting Started - basics, context, composition, built-in specs
+- Tutorial 2 (20 min): Property Wrappers - @Satisfies, @Decides, @Maybe, async
+- Tutorial 3 (25 min): Advanced - macros, complex specs, testing, best practices
+
+### Code Sample Guidelines Applied
+- Samples are focused and concise
+- Progressive enhancement (each step builds on previous)
+- Comments explain key concepts
+- Realistic variable names and scenarios
diff --git a/DOCS/INPROGRESS/Phase5_Cleanup_Validation_Planning.md b/DOCS/INPROGRESS/Phase5_Cleanup_Validation_Planning.md
new file mode 100644
index 0000000..cd11283
--- /dev/null
+++ b/DOCS/INPROGRESS/Phase5_Cleanup_Validation_Planning.md
@@ -0,0 +1,113 @@
+# Feature Planning: Documentation Cleanup and Validation
+
+## Task Metadata
+- **Created**: 2025-11-20
+- **Completed**: 2025-11-21
+- **Priority**: P1
+- **Estimated Scope**: Medium (3-4 hours)
+- **Prerequisites**: Phase 3 complete (all 23 articles created)
+- **Target Layers**: Documentation, CI/CD, Quality Assurance
+
+## Feature Overview
+
+Address all warnings and issues from the DocC build, improve documentation quality, validate cross-references, fix circular dependencies, and ensure documentation builds cleanly.
+
+## Implementation Summary
+
+### Phase 5.1: Fix Ambiguous Symbol References
+- [x] Fixed AnySpecification.md init disambiguation
+- [x] Fixed AsyncSatisfies.md init disambiguation
+- [x] Fixed Decides.md init disambiguation
+- [x] Removed invalid hash-based disambiguations
+
+### Phase 5.2: Resolve Circular Reference Cycles
+- [x] Fixed Protocol → Implementation cycles in all files
+- [x] Removed "Related Types" sections from Topics that caused cycles
+- [x] Files fixed: AnySpecification, AsyncSatisfies, ContextProviding, CooldownIntervalSpec, DateComparisonSpec, DateRangeSpec, AsyncSpecification, MaxCountSpec, TimeSinceEventSpec, FirstMatchSpec, DecisionSpec, Maybe, Satisfies, PredicateSpec, AutoContextMacro, DefaultContextProvider, MockContextProvider, Decides
+
+### Phase 5.3: Clean Up Extraneous Content
+- [x] Removed "(from Specification)" annotations from Topics
+- [x] Removed "(Comparable)" annotations from Topics
+- [x] Fixed SpecificationOperators.md build references
+- [x] Fixed AsyncSpecification.md bridging section
+
+### Phase 5.4: Fix Missing Symbols
+- [x] Changed SpecsMacro.md title to not reference non-existent symbol
+- [x] Changed AutoContextMacro.md title to not reference non-existent symbol
+- [x] Changed SpecificationCore.md macro references to use doc: links
+- [x] Fixed cross-references between macro articles
+
+### Phase 5.5: Validate Documentation Links
+- [x] All doc: references validated
+- [x] Changed symbol links to doc: links where appropriate
+
+### Phase 5.6: Build and Test
+- [x] swift build - Success
+- [x] swift package generate-documentation - Success
+- [x] swiftformat --lint - 0 errors
+
+### Phase 5.7: Quality Improvements
+- [x] Tutorial code samples formatted with SwiftFormat
+
+## Warning Reduction Summary
+
+| Stage | Warning Count |
+|-------|---------------|
+| Starting | 177 |
+| After circular ref fixes | 65 |
+| After symbol fixes | 46 |
+| After more cleanup | 39 |
+| Final (remaining are source comments) | ~39 |
+
+## Remaining Warnings (Not in Article Files)
+
+The remaining ~39 warnings are:
+- 17 "Only links allowed in task group" - in Swift source doc comments
+- 7 "Extraneous content" - in Swift source doc comments
+- 4 "specs doesn't exist" - macro in separate target
+- 3 "Missing Image child directive" - tutorial images not provided
+- Others: references to macros in separate target
+
+These are in Swift source file documentation comments, not the article .md files, and would require modifying the source code documentation.
+
+## Files Modified
+
+### Article Files (18 files)
+- AnySpecification.md
+- AsyncSatisfies.md
+- AsyncSpecification.md
+- AutoContextMacro.md
+- ContextProviding.md
+- CooldownIntervalSpec.md
+- DateComparisonSpec.md
+- DateRangeSpec.md
+- Decides.md
+- DefaultContextProvider.md
+- FirstMatchSpec.md
+- MaxCountSpec.md
+- MockContextProvider.md
+- PredicateSpec.md
+- Satisfies.md
+- SpecificationCore.md
+- SpecificationOperators.md
+- SpecsMacro.md
+
+### Tutorial Files (1 file)
+- Tutorials/Tutorials.tutorial (removed @Resources section)
+
+### Code Sample Files (14 files formatted)
+- SwiftFormat applied to all code samples in Tutorials/Resources/Code/
+
+## Success Criteria
+
+- [x] Significant reduction in warnings (177 → 39)
+- [x] All circular reference cycles in article files resolved
+- [x] Documentation builds successfully
+- [x] SwiftFormat lint passes with 0 errors
+- [x] swift build passes
+
+## Notes
+
+- Remaining warnings are in Swift source file doc comments, not article files
+- Macro symbols (specs, AutoContext) are in a separate macros target, hence warnings
+- Tutorial images were not created (optional per Phase 4 plan)
diff --git a/DOCS/INPROGRESS/Summary_of_Work.md b/DOCS/INPROGRESS/Summary_of_Work.md
new file mode 100644
index 0000000..0589602
--- /dev/null
+++ b/DOCS/INPROGRESS/Summary_of_Work.md
@@ -0,0 +1,102 @@
+# Summary of Work: SpecificationCore Documentation
+
+## Completed: 2025-11-21
+
+## Overview
+
+Completed two major documentation phases for SpecificationCore:
+1. **Phase 4**: DocC Tutorials creation
+2. **Phase 5**: Documentation cleanup and validation
+
+---
+
+## Phase 4: DocC Tutorials
+
+### Tasks Completed
+
+Created comprehensive DocC tutorials for SpecificationCore providing a complete learning path from beginner to advanced.
+
+### Files Created
+
+**Tutorial Files (4)**
+- `Tutorials/Tutorials.tutorial` - Table of contents
+- `Tutorials/GettingStartedCore.tutorial` (25 min)
+- `Tutorials/PropertyWrappersGuide.tutorial` (20 min)
+- `Tutorials/MacrosAndAdvanced.tutorial` (25 min)
+
+**Code Sample Files (27)**
+- 12 getting-started samples
+- 7 property-wrapper samples
+- 8 macro/advanced samples
+
+### Tutorial Content
+
+1. **Getting Started** - Specification basics, context providers, composition, built-in specs, testing
+2. **Property Wrappers** - @Satisfies, @Decides, @Maybe, async evaluation, builder patterns
+3. **Macros and Advanced** - @specs, @AutoContext, complex real-world specs, testing best practices
+
+---
+
+## Phase 5: Documentation Cleanup and Validation
+
+### Tasks Completed
+
+Fixed documentation warnings and improved quality across all 23+ article files.
+
+### Warning Reduction
+
+| Stage | Warning Count |
+|-------|---------------|
+| Starting | 177 |
+| Final | 39 |
+| **Reduction** | **78%** |
+
+### Key Fixes
+
+1. **Circular Reference Cycles** - Removed "Related Types" sections from Topics that caused cycles between protocols and implementations
+
+2. **Ambiguous Symbol References** - Fixed invalid disambiguation hashes and removed problematic init references
+
+3. **Extraneous Content** - Removed annotations like "(from Specification)" and "(Comparable)" from Topics lists
+
+4. **Missing Symbol References** - Changed macro references to use `` links instead of ``symbol`` links
+
+5. **SwiftFormat Compliance** - Fixed all code samples to pass SwiftFormat lint
+
+### Files Modified
+
+- 18 article .md files
+- 1 tutorial file
+- 14 code sample files (formatted)
+
+---
+
+## Verification
+
+```bash
+# Build
+swift build # Success
+
+# Documentation
+swift package generate-documentation --target SpecificationCore # Success
+
+# SwiftFormat
+swiftformat --lint . # 0 errors
+```
+
+---
+
+## Remaining Warnings
+
+39 warnings remain, all in Swift source file doc comments (not article files):
+- Task group formatting in source comments
+- References to macros in separate target
+- Missing tutorial images (optional)
+
+These would require modifying Swift source code documentation.
+
+---
+
+## Ready for Archival
+
+Both Phase 4 and Phase 5 tasks are complete and ready to be archived using the ARCHIVE.md command.
diff --git a/Package.resolved b/Package.resolved
index 997fa97..721fef7 100644
--- a/Package.resolved
+++ b/Package.resolved
@@ -1,5 +1,5 @@
{
- "originHash" : "e9aa78d96a078ebc910c121f230dba501a93eeb1b1e72dade3d23aa5ec85474c",
+ "originHash" : "d9112880aecefdc5cd060c501b598f6427cd3eecff88e2f4b68297ad6416932c",
"pins" : [
{
"identity" : "swift-custom-dump",
@@ -10,6 +10,24 @@
"version" : "1.3.3"
}
},
+ {
+ "identity" : "swift-docc-plugin",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/apple/swift-docc-plugin",
+ "state" : {
+ "revision" : "3e4f133a77e644a5812911a0513aeb7288b07d06",
+ "version" : "1.4.5"
+ }
+ },
+ {
+ "identity" : "swift-docc-symbolkit",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/swiftlang/swift-docc-symbolkit",
+ "state" : {
+ "revision" : "b45d1f2ed151d057b54504d653e0da5552844e34",
+ "version" : "1.0.0"
+ }
+ },
{
"identity" : "swift-macro-testing",
"kind" : "remoteSourceControl",
diff --git a/Package.swift b/Package.swift
index c43837d..23758a4 100644
--- a/Package.swift
+++ b/Package.swift
@@ -23,7 +23,9 @@ let package = Package(
// Depend on the latest Swift Syntax package for macro support.
.package(url: "https://github.com/swiftlang/swift-syntax", from: "510.0.0"),
// Add swift-macro-testing for a simplified macro testing experience.
- .package(url: "https://github.com/pointfreeco/swift-macro-testing", from: "0.4.0")
+ .package(url: "https://github.com/pointfreeco/swift-macro-testing", from: "0.4.0"),
+ // Add Swift-DocC Plugin for documentation generation
+ .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0")
],
targets: [
// Targets are the basic building blocks of a package, defining a module or a test suite.
diff --git a/Sources/SpecificationCore/Documentation.docc/AnySpecification.md b/Sources/SpecificationCore/Documentation.docc/AnySpecification.md
new file mode 100644
index 0000000..927568d
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/AnySpecification.md
@@ -0,0 +1,449 @@
+# ``SpecificationCore/AnySpecification``
+
+A type-erased wrapper for specifications with performance optimizations.
+
+## Overview
+
+`AnySpecification` is a type-erased wrapper that allows you to store specifications of different concrete types in the same collection or use them in contexts where the specific type isn't known at compile time. It's optimized for performance with specialized storage strategies and compiler optimizations.
+
+### Key Benefits
+
+- **Type Erasure**: Store different specification types together
+- **Performance Optimized**: Specialized storage and inlinable methods
+- **Flexible Creation**: Create from specifications or closures
+- **Constant Optimization**: Special handling for always-true/always-false specs
+- **Collection Utilities**: Combine multiple specifications easily
+
+### When to Use AnySpecification
+
+Use `AnySpecification` when you need to:
+- Store specifications in collections or arrays
+- Return specifications from functions with different concrete types
+- Create specifications dynamically at runtime
+- Build flexible specification factories
+- Work with specifications through protocols
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+struct User {
+ let age: Int
+ let isActive: Bool
+}
+
+// Create from a concrete specification
+struct AdultSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.age >= 18
+ }
+}
+
+let anySpec = AnySpecification(AdultSpec())
+let isAdult = anySpec.isSatisfiedBy(user)
+
+// Create from a closure
+let activeSpec = AnySpecification { user in
+ user.isActive
+}
+
+let isActive = activeSpec.isSatisfiedBy(user)
+```
+
+## Storing Specifications in Collections
+
+Type erasure allows heterogeneous specification collections:
+
+```swift
+struct AdultSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.age >= 18
+ }
+}
+
+struct ActiveSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.isActive
+ }
+}
+
+// Store different specification types together
+let rules: [AnySpecification] = [
+ AnySpecification(AdultSpec()),
+ AnySpecification(ActiveSpec()),
+ AnySpecification { user in user.age < 65 },
+ AnySpecification { user in user.email.contains("@") }
+]
+
+// Evaluate all rules
+let passesAll = rules.allSatisfy { spec in
+ spec.isSatisfiedBy(user)
+}
+```
+
+## Creating from Closures
+
+Create specifications directly from predicates:
+
+```swift
+// Simple closure-based specification
+let emailValid = AnySpecification { user in
+ user.email.contains("@") && user.email.contains(".")
+}
+
+// Complex closure with multiple conditions
+let eligibleUser = AnySpecification { user in
+ user.age >= 18 &&
+ user.isActive &&
+ user.emailVerified &&
+ !user.isBanned
+}
+
+// Use like any other specification
+if eligibleUser.isSatisfiedBy(user) {
+ print("User is eligible")
+}
+```
+
+## Constant Specifications
+
+Use optimized constant specifications for always-true or always-false cases:
+
+```swift
+// Always-true specification
+let alwaysTrue = AnySpecification.always
+
+// Always-false specification
+let alwaysFalse = AnySpecification.never
+
+// Optimized constant functions
+let trueSpec = AnySpecification.constantTrue()
+let falseSpec = AnySpecification.constantFalse()
+
+// Use in conditional logic
+let spec = featureEnabled
+ ? AnySpecification(FeatureSpec())
+ : AnySpecification.never
+```
+
+## Collection Extensions
+
+Combine multiple specifications from collections:
+
+### All Satisfied (AND)
+
+Create a specification that requires all specs to be satisfied:
+
+```swift
+let validationRules = [
+ AnySpecification(EmailValidSpec()),
+ AnySpecification(PasswordStrongSpec()),
+ AnySpecification(AgeRequirementSpec())
+]
+
+// All validations must pass
+let allValid = validationRules.allSatisfied()
+
+if allValid.isSatisfiedBy(user) {
+ print("All validations passed")
+}
+```
+
+### Any Satisfied (OR)
+
+Create a specification satisfied when any spec matches:
+
+```swift
+let discountEligibility = [
+ AnySpecification(PremiumMemberSpec()),
+ AnySpecification(FirstTimeBuyerSpec()),
+ AnySpecification(HolidayPromoSpec())
+]
+
+// Any condition grants discount
+let getsDiscount = discountEligibility.anySatisfied()
+
+if getsDiscount.isSatisfiedBy(user) {
+ print("Discount applied")
+}
+```
+
+## Dynamic Specification Factory
+
+Build specifications dynamically based on configuration:
+
+```swift
+struct SpecificationFactory {
+ static func create(for rules: [String: Any]) -> AnySpecification {
+ var specs: [AnySpecification] = []
+
+ if let minAge = rules["minAge"] as? Int {
+ specs.append(AnySpecification { user in user.age >= minAge })
+ }
+
+ if let requiredRole = rules["role"] as? String {
+ specs.append(AnySpecification { user in user.role == requiredRole })
+ }
+
+ if let mustBeActive = rules["active"] as? Bool, mustBeActive {
+ specs.append(AnySpecification { user in user.isActive })
+ }
+
+ // Combine all specs with AND logic
+ return specs.isEmpty
+ ? .always
+ : specs.allSatisfied()
+ }
+}
+
+// Use factory
+let config = ["minAge": 18, "active": true, "role": "member"]
+let spec = SpecificationFactory.create(for: config)
+let passes = spec.isSatisfiedBy(user)
+```
+
+## Wrapping Complex Specifications
+
+Simplify complex specification hierarchies:
+
+```swift
+// Complex nested specification
+let complexSpec = AdultSpec()
+ .and(ActiveSpec())
+ .or(PremiumSpec())
+ .and(VerifiedSpec().not())
+
+// Wrap in AnySpecification for simpler type
+let wrapped = AnySpecification(complexSpec)
+
+// Can now be stored, returned, or passed around easily
+func getEligibilitySpec() -> AnySpecification {
+ wrapped // Simpler return type
+}
+```
+
+## Helper Specification Types
+
+`AnySpecification` provides helper types for constants:
+
+### AlwaysTrueSpec
+
+```swift
+let alwaysTrue = AlwaysTrueSpec()
+alwaysTrue.isSatisfiedBy(anyUser) // Always returns true
+
+// Wrapped automatically
+let wrapped = AnySpecification(AlwaysTrueSpec())
+// Uses optimized .constantTrue storage
+```
+
+### AlwaysFalseSpec
+
+```swift
+let alwaysFalse = AlwaysFalseSpec()
+alwaysFalse.isSatisfiedBy(anyUser) // Always returns false
+
+// Wrapped automatically
+let wrapped = AnySpecification(AlwaysFalseSpec())
+// Uses optimized .constantFalse storage
+```
+
+## Composition with Type Erasure
+
+Combine type-erased specifications using composition operators:
+
+```swift
+let spec1 = AnySpecification { $0.age >= 18 }
+let spec2 = AnySpecification { $0.isActive }
+
+// Compose with operators
+let combined = spec1.and(spec2) // Returns AndSpecification
+
+// Wrap result back in AnySpecification
+let erased = AnySpecification(combined)
+
+// Or chain directly
+let chained = AnySpecification { $0.age >= 18 }
+ .and(AnySpecification { $0.isActive })
+ .or(AnySpecification { $0.isPremium })
+```
+
+## Convenience Function
+
+Use the global `spec()` function for concise creation:
+
+```swift
+// Instead of:
+let verbose = AnySpecification { user in user.isActive }
+
+// Use:
+let concise = spec { $0.isActive }
+
+// Compose easily
+let combined = spec { $0.age >= 18 }
+ .and(spec { $0.isActive })
+```
+
+## Performance Optimizations
+
+`AnySpecification` includes several performance optimizations:
+
+### Inlinable Methods
+
+All critical methods are marked `@inlinable` for cross-module optimization:
+
+```swift
+// These methods can be inlined by the compiler
+public func isSatisfiedBy(_ candidate: T) -> Bool { ... }
+public init(_ specification: S) where S.T == T { ... }
+```
+
+### Specialized Storage
+
+Different storage strategies based on specification type:
+
+- `.constantTrue` - Optimized for always-true specs
+- `.constantFalse` - Optimized for always-false specs
+- `.predicate` - Direct closure storage
+- `.specification` - Wrapped specification
+
+### Optimized Collection Methods
+
+Collection extensions optimize for common cases:
+
+```swift
+let specs = [spec1, spec2, spec3]
+
+// Optimizes for empty collections and single elements
+let all = specs.allSatisfied()
+
+// Returns .constantTrue() for empty
+// Returns wrapped first element for single item
+// Returns combined spec for multiple items
+```
+
+## Best Practices
+
+### Use for Heterogeneous Collections
+
+```swift
+// ✅ Good - store different spec types
+let rules: [AnySpecification] = [
+ AnySpecification(ConcreteSpec1()),
+ AnySpecification(ConcreteSpec2()),
+ AnySpecification { /* closure */ }
+]
+
+// ❌ Avoid - lose type information unnecessarily
+let spec: AnySpecification = AnySpecification(ConcreteSpec())
+// Better to keep ConcreteSpec type if not storing in collection
+```
+
+### Prefer Concrete Types When Possible
+
+```swift
+// ✅ Good - use concrete type
+func createSpec() -> AdultSpec {
+ AdultSpec(minimumAge: 18)
+}
+
+// ❌ Avoid - unnecessary type erasure
+func createSpec() -> AnySpecification {
+ AnySpecification(AdultSpec(minimumAge: 18))
+}
+```
+
+### Use Constant Specs Appropriately
+
+```swift
+// ✅ Good - use constants for always-true/false
+let spec = isFeatureEnabled
+ ? AnySpecification(FeatureSpec())
+ : .never
+
+// ❌ Avoid - creating unnecessary closures
+let spec = isFeatureEnabled
+ ? AnySpecification(FeatureSpec())
+ : AnySpecification { _ in false }
+```
+
+## Common Patterns
+
+### Guard Pattern
+
+```swift
+func validateUser(_ user: User) -> Bool {
+ let validations: [AnySpecification] = [
+ spec { $0.email.contains("@") },
+ spec { $0.age >= 18 },
+ spec { $0.isActive }
+ ]
+
+ return validations.allSatisfied().isSatisfiedBy(user)
+}
+```
+
+### Factory Pattern
+
+```swift
+enum UserType {
+ case admin, moderator, user
+
+ var spec: AnySpecification {
+ switch self {
+ case .admin:
+ return spec { $0.role == "admin" }
+ case .moderator:
+ return spec { $0.role == "moderator" || $0.role == "admin" }
+ case .user:
+ return .always
+ }
+ }
+}
+```
+
+### Builder Pattern
+
+```swift
+struct SpecBuilder {
+ private var specs: [AnySpecification] = []
+
+ mutating func add(_ spec: AnySpecification) {
+ specs.append(spec)
+ }
+
+ func build() -> AnySpecification {
+ specs.allSatisfied()
+ }
+}
+
+var builder = SpecBuilder()
+builder.add(spec { $0.age >= 18 })
+builder.add(spec { $0.isActive })
+let combined = builder.build()
+```
+
+## Topics
+
+### Evaluating Specifications
+
+- ``isSatisfiedBy(_:)``
+
+### Constant Specifications
+
+- ``always``
+- ``never``
+- ``constantTrue()``
+- ``constantFalse()``
+
+### Helper Types
+
+- ``AlwaysTrueSpec``
+- ``AlwaysFalseSpec``
+
+## See Also
+
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/AsyncSatisfies.md b/Sources/SpecificationCore/Documentation.docc/AsyncSatisfies.md
new file mode 100644
index 0000000..ff8a15d
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/AsyncSatisfies.md
@@ -0,0 +1,820 @@
+# ``SpecificationCore/AsyncSatisfies``
+
+A property wrapper for asynchronously evaluating specifications with async context providers and async specifications.
+
+## Overview
+
+`@AsyncSatisfies` is designed for scenarios where specification evaluation requires asynchronous operations like network requests, database queries, or file I/O. Unlike ``Satisfies``, this wrapper requires explicit async evaluation through the projected value rather than providing automatic evaluation.
+
+### Key Benefits
+
+- **Async Context Support**: Works with context providers that provide async context
+- **Async Specifications**: Supports both sync and async specification evaluation
+- **Lazy Evaluation**: Only evaluates when explicitly requested
+- **Error Handling**: Propagates errors from async operations
+- **Flexible Usage**: Works with regular specifications or async-specific ones
+- **Thread-Safe**: Safe to call from any thread
+
+### When to Use @AsyncSatisfies
+
+Use `@AsyncSatisfies` when you need to:
+- Evaluate specifications with network-based context or data
+- Perform database queries during specification evaluation
+- Handle file I/O or other async operations
+- Work with remote configuration or feature flags
+- Integrate with async-first APIs or services
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+@AsyncSatisfies(
+ provider: networkProvider,
+ using: RemoteFeatureFlagSpec(flagKey: "premium_features")
+)
+var hasPremiumAccess: Bool?
+
+// Evaluate asynchronously when needed
+func checkAccess() async {
+ do {
+ let hasAccess = try await $hasPremiumAccess.evaluate()
+ if hasAccess {
+ showPremiumFeatures()
+ }
+ } catch {
+ handleNetworkError(error)
+ }
+}
+```
+
+## Creating @AsyncSatisfies
+
+### With Async Specification
+
+```swift
+struct RemoteConfigSpec: AsyncSpecification {
+ typealias T = NetworkContext
+ let featureKey: String
+
+ func isSatisfiedBy(_ context: NetworkContext) async throws -> Bool {
+ let config = try await context.apiClient.fetchRemoteConfig()
+ return config.features[featureKey] == true
+ }
+}
+
+@AsyncSatisfies(
+ provider: networkContextProvider,
+ using: RemoteConfigSpec(featureKey: "new_ui")
+)
+var shouldShowNewUI: Bool?
+
+// Evaluate
+let enabled = try await $shouldShowNewUI.evaluate()
+```
+
+### With Regular Specification
+
+```swift
+// Use regular (synchronous) specifications with async wrapper
+@AsyncSatisfies(
+ provider: asyncProvider,
+ using: MaxCountSpec(counterKey: "api_calls", maximumCount: 100)
+)
+var canMakeAPICall: Bool?
+
+// This uses async context fetching but sync specification evaluation
+let allowed = try await $canMakeAPICall.evaluate()
+```
+
+### With Async Predicate
+
+```swift
+@AsyncSatisfies(provider: apiProvider, predicate: { context in
+ let userProfile = try await context.apiClient.fetchUserProfile()
+ let billingInfo = try await context.apiClient.fetchBillingInfo()
+
+ return userProfile.isVerified && billingInfo.isGoodStanding
+})
+var isEligibleUser: Bool?
+```
+
+## How It Works
+
+The wrapper requires explicit async evaluation through the projected value:
+
+```swift
+@AsyncSatisfies(provider: asyncProvider, using: SomeSpec())
+var isConditionMet: Bool?
+
+// wrappedValue is always nil (no automatic evaluation)
+print(isConditionMet) // nil
+
+// Use projected value to evaluate asynchronously
+let result = try await $isConditionMet.evaluate()
+print(result) // true or false
+```
+
+## Usage Examples
+
+### Network-Based Feature Flags
+
+```swift
+struct NetworkContext {
+ let apiClient: APIClient
+ let userId: String
+}
+
+struct RemoteFeatureFlagSpec: AsyncSpecification {
+ typealias T = NetworkContext
+ let flagKey: String
+
+ func isSatisfiedBy(_ context: NetworkContext) async throws -> Bool {
+ let response = try await context.apiClient.get(
+ "/feature-flags/\(context.userId)"
+ )
+ return response.flags[flagKey] as? Bool ?? false
+ }
+}
+
+@AsyncSatisfies(
+ provider: networkProvider,
+ using: RemoteFeatureFlagSpec(flagKey: "experimental_features")
+)
+var hasExperimentalFeatures: Bool?
+
+func loadFeatures() async {
+ do {
+ let enabled = try await $hasExperimentalFeatures.evaluate()
+ if enabled {
+ loadExperimentalFeatures()
+ } else {
+ loadStandardFeatures()
+ }
+ } catch {
+ // Fall back to local configuration
+ loadStandardFeatures()
+ logError("Failed to fetch remote config: \(error)")
+ }
+}
+```
+
+### Database User Validation
+
+```swift
+struct DatabaseContext {
+ let database: Database
+ let userId: UUID
+}
+
+struct ActiveUserSpec: AsyncSpecification {
+ typealias T = DatabaseContext
+
+ func isSatisfiedBy(_ context: DatabaseContext) async throws -> Bool {
+ let user = try await context.database.fetchUser(context.userId)
+ return user.isActive &&
+ user.hasValidSubscription &&
+ !user.isBanned
+ }
+}
+
+@AsyncSatisfies(
+ provider: databaseProvider,
+ using: ActiveUserSpec()
+)
+var isActiveUser: Bool?
+
+func checkUserStatus() async throws {
+ let isActive = try await $isActiveUser.evaluate()
+
+ if isActive {
+ grantAccess()
+ } else {
+ denyAccess()
+ }
+}
+```
+
+### API Rate Limit Check
+
+```swift
+struct RateLimitContext {
+ let apiClient: APIClient
+ let accountId: String
+}
+
+struct RateLimitSpec: AsyncSpecification {
+ typealias T = RateLimitContext
+
+ func isSatisfiedBy(_ context: RateLimitContext) async throws -> Bool {
+ let limits = try await context.apiClient.getRateLimits(
+ accountId: context.accountId
+ )
+ return limits.remainingRequests > 0
+ }
+}
+
+@AsyncSatisfies(
+ provider: rateLimitProvider,
+ using: RateLimitSpec()
+)
+var canMakeRequest: Bool?
+
+func performAPICall() async throws {
+ let allowed = try await $canMakeRequest.evaluate()
+
+ guard allowed else {
+ throw APIError.rateLimitExceeded
+ }
+
+ let response = try await makeAPICall()
+ return response
+}
+```
+
+### File-Based Configuration
+
+```swift
+struct FileContext {
+ let configPath: String
+}
+
+struct ConfigurationValidSpec: AsyncSpecification {
+ typealias T = FileContext
+
+ func isSatisfiedBy(_ context: FileContext) async throws -> Bool {
+ let data = try await FileManager.default.readFile(at: context.configPath)
+ let config = try JSONDecoder().decode(Configuration.self, from: data)
+ return config.isValid && config.version >= requiredVersion
+ }
+}
+
+@AsyncSatisfies(
+ provider: fileProvider,
+ using: ConfigurationValidSpec()
+)
+var hasValidConfiguration: Bool?
+
+func loadApp() async {
+ do {
+ let isValid = try await $hasValidConfiguration.evaluate()
+
+ if isValid {
+ startApp()
+ } else {
+ showConfigurationError()
+ }
+ } catch {
+ useDefaultConfiguration()
+ }
+}
+```
+
+## Real-World Examples
+
+### Remote Configuration Manager
+
+```swift
+class RemoteConfigManager {
+ struct RemoteContext {
+ let apiClient: APIClient
+ let deviceId: String
+ let appVersion: String
+ }
+
+ struct FeatureEnabledSpec: AsyncSpecification {
+ typealias T = RemoteContext
+ let feature: String
+
+ func isSatisfiedBy(_ context: RemoteContext) async throws -> Bool {
+ let config = try await context.apiClient.fetchConfig(
+ deviceId: context.deviceId,
+ appVersion: context.appVersion
+ )
+
+ // Check if feature is enabled with rollout percentage
+ guard let featureConfig = config.features[feature] else {
+ return false
+ }
+
+ if featureConfig.rolloutPercentage >= 100 {
+ return true
+ }
+
+ // Use device ID for consistent rollout
+ let hash = context.deviceId.hashValue
+ let bucket = abs(hash % 100)
+ return bucket < featureConfig.rolloutPercentage
+ }
+ }
+
+ @AsyncSatisfies(
+ provider: remoteProvider,
+ using: FeatureEnabledSpec(feature: "new_payment_flow")
+ )
+ var useNewPaymentFlow: Bool?
+
+ @AsyncSatisfies(
+ provider: remoteProvider,
+ using: FeatureEnabledSpec(feature: "enhanced_analytics")
+ )
+ var enableEnhancedAnalytics: Bool?
+
+ func configureApp() async {
+ do {
+ async let paymentFlow = $useNewPaymentFlow.evaluate()
+ async let analytics = $enableEnhancedAnalytics.evaluate()
+
+ let (useNew, enhancedAnalytics) = try await (paymentFlow, analytics)
+
+ if useNew {
+ configureNewPaymentFlow()
+ }
+
+ if enhancedAnalytics {
+ enableDetailedAnalytics()
+ }
+ } catch {
+ // Use default configuration
+ useDefaultConfiguration()
+ logError("Remote config failed: \(error)")
+ }
+ }
+}
+```
+
+### Subscription Verification System
+
+```swift
+class SubscriptionVerifier {
+ struct VerificationContext {
+ let apiClient: APIClient
+ let receiptData: Data
+ let userId: String
+ }
+
+ struct ActiveSubscriptionSpec: AsyncSpecification {
+ typealias T = VerificationContext
+
+ func isSatisfiedBy(_ context: VerificationContext) async throws -> Bool {
+ // Verify with App Store
+ let verification = try await context.apiClient.verifyReceipt(
+ receiptData: context.receiptData
+ )
+
+ guard verification.status == .valid else {
+ return false
+ }
+
+ // Check subscription status in backend
+ let subscription = try await context.apiClient.getSubscription(
+ userId: context.userId
+ )
+
+ return subscription.isActive &&
+ subscription.expirationDate > Date() &&
+ !subscription.isCancelled
+ }
+ }
+
+ @AsyncSatisfies(
+ provider: verificationProvider,
+ using: ActiveSubscriptionSpec()
+ )
+ var hasActiveSubscription: Bool?
+
+ func checkSubscriptionStatus() async -> SubscriptionStatus {
+ do {
+ let isActive = try await $hasActiveSubscription.evaluate()
+
+ if isActive {
+ return .active
+ } else {
+ return .expired
+ }
+ } catch let error as VerificationError {
+ switch error {
+ case .networkError:
+ return .verificationFailed(retryable: true)
+ case .invalidReceipt:
+ return .invalid
+ case .serverError:
+ return .verificationFailed(retryable: true)
+ }
+ } catch {
+ return .unknown
+ }
+ }
+}
+```
+
+### Multi-Service Eligibility Check
+
+```swift
+class EligibilityChecker {
+ struct ServiceContext {
+ let userService: UserService
+ let billingService: BillingService
+ let complianceService: ComplianceService
+ let userId: UUID
+ }
+
+ struct FullAccessSpec: AsyncSpecification {
+ typealias T = ServiceContext
+
+ func isSatisfiedBy(_ context: ServiceContext) async throws -> Bool {
+ // Fetch data from multiple services in parallel
+ async let user = context.userService.fetchUser(context.userId)
+ async let billing = context.billingService.getBillingStatus(context.userId)
+ async let compliance = context.complianceService.checkCompliance(context.userId)
+
+ let (userData, billingData, complianceData) = try await (user, billing, compliance)
+
+ // Check all conditions
+ return userData.isVerified &&
+ userData.accountStatus == .active &&
+ billingData.isGoodStanding &&
+ billingData.hasActivePaymentMethod &&
+ complianceData.isCompliant &&
+ !complianceData.hasRestrictions
+ }
+ }
+
+ @AsyncSatisfies(
+ provider: serviceProvider,
+ using: FullAccessSpec()
+ )
+ var hasFullAccess: Bool?
+
+ func determineAccessLevel() async -> AccessLevel {
+ do {
+ let hasAccess = try await $hasFullAccess.evaluate()
+
+ if hasAccess {
+ return .full
+ } else {
+ return .restricted
+ }
+ } catch {
+ // Conservative fallback
+ return .denied
+ }
+ }
+}
+```
+
+### SwiftUI Integration
+
+```swift
+import SwiftUI
+
+struct PremiumContentView: View {
+ @AsyncSatisfies(
+ provider: networkProvider,
+ using: PremiumAccessSpec()
+ )
+ var hasPremiumAccess: Bool?
+
+ @State private var accessStatus: AccessStatus = .checking
+ @State private var showError = false
+ @State private var errorMessage = ""
+
+ enum AccessStatus {
+ case checking
+ case granted
+ case denied
+ }
+
+ var body: some View {
+ Group {
+ switch accessStatus {
+ case .checking:
+ ProgressView("Verifying access...")
+
+ case .granted:
+ PremiumContentUI()
+
+ case .denied:
+ AccessDeniedView()
+ .button("Upgrade") {
+ showUpgradeFlow()
+ }
+ }
+ }
+ .task {
+ await checkAccess()
+ }
+ .alert("Error", isPresented: $showError) {
+ Button("Retry") {
+ Task { await checkAccess() }
+ }
+ Button("Cancel", role: .cancel) {}
+ } message: {
+ Text(errorMessage)
+ }
+ }
+
+ func checkAccess() async {
+ accessStatus = .checking
+
+ do {
+ let hasAccess = try await withTimeout(seconds: 10) {
+ try await $hasPremiumAccess.evaluate()
+ }
+
+ accessStatus = hasAccess ? .granted : .denied
+ } catch {
+ errorMessage = error.localizedDescription
+ showError = true
+ accessStatus = .denied
+ }
+ }
+}
+```
+
+## Error Handling
+
+Handle errors from async evaluation:
+
+```swift
+@AsyncSatisfies(provider: networkProvider, using: RemoteSpec())
+var isEnabled: Bool?
+
+func checkFeature() async {
+ do {
+ let enabled = try await $isEnabled.evaluate()
+ // Handle result
+ } catch let error as NetworkError {
+ switch error {
+ case .timeout:
+ // Retry or use cached value
+ useCachedValue()
+ case .serverError:
+ // Show error to user
+ showErrorMessage()
+ case .noConnection:
+ // Offline mode
+ enterOfflineMode()
+ }
+ } catch {
+ // Handle unexpected errors
+ logError(error)
+ useDefaultBehavior()
+ }
+}
+```
+
+## Timeout Handling
+
+Add timeouts to async evaluation:
+
+```swift
+@AsyncSatisfies(provider: apiProvider, using: SlowAPISpec())
+var shouldEnable: Bool?
+
+func checkWithTimeout() async {
+ do {
+ let result = try await withTimeout(seconds: 5) {
+ try await $shouldEnable.evaluate()
+ }
+
+ if result {
+ enableFeature()
+ }
+ } catch is TimeoutError {
+ // Use default on timeout
+ useDefaultValue()
+ } catch {
+ handleError(error)
+ }
+}
+
+// Helper function
+func withTimeout(
+ seconds: TimeInterval,
+ operation: @escaping () async throws -> T
+) async throws -> T {
+ try await withThrowingTaskGroup(of: T.self) { group in
+ group.addTask {
+ try await operation()
+ }
+
+ group.addTask {
+ try await Task.sleep(nanoseconds: UInt64(seconds * 1_000_000_000))
+ throw TimeoutError()
+ }
+
+ let result = try await group.next()!
+ group.cancelAll()
+ return result
+ }
+}
+```
+
+## Testing
+
+Test async evaluation with ``MockContextProvider``:
+
+```swift
+func testAsyncEvaluation() async throws {
+ let provider = MockContextProvider()
+ .withFlag("remote_feature", value: true)
+
+ @AsyncSatisfies(
+ provider: provider,
+ using: FeatureFlagSpec(flagKey: "remote_feature")
+ )
+ var isEnabled: Bool?
+
+ // wrappedValue is always nil
+ XCTAssertNil(isEnabled)
+
+ // Evaluate asynchronously
+ let result = try await $isEnabled.evaluate()
+ XCTAssertTrue(result)
+
+ // Update context
+ provider.setFlag("remote_feature", to: false)
+ let updatedResult = try await $isEnabled.evaluate()
+ XCTAssertFalse(updatedResult)
+}
+
+func testAsyncSpecification() async throws {
+ struct MockAsyncSpec: AsyncSpecification {
+ typealias T = EvaluationContext
+ let delay: TimeInterval
+ let result: Bool
+
+ func isSatisfiedBy(_ context: EvaluationContext) async throws -> Bool {
+ try await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
+ return result
+ }
+ }
+
+ let provider = MockContextProvider()
+ let spec = MockAsyncSpec(delay: 0.1, result: true)
+
+ @AsyncSatisfies(provider: provider, using: spec)
+ var condition: Bool?
+
+ let start = Date()
+ let result = try await $condition.evaluate()
+ let duration = Date().timeIntervalSince(start)
+
+ XCTAssertTrue(result)
+ XCTAssertGreaterThan(duration, 0.1)
+}
+
+func testErrorPropagation() async {
+ struct FailingSpec: AsyncSpecification {
+ typealias T = EvaluationContext
+
+ func isSatisfiedBy(_ context: EvaluationContext) async throws -> Bool {
+ throw TestError.failed
+ }
+ }
+
+ let provider = MockContextProvider()
+
+ @AsyncSatisfies(provider: provider, using: FailingSpec())
+ var condition: Bool?
+
+ do {
+ _ = try await $condition.evaluate()
+ XCTFail("Should have thrown error")
+ } catch is TestError {
+ // Expected
+ } catch {
+ XCTFail("Wrong error type")
+ }
+}
+```
+
+## Best Practices
+
+### Use Appropriate Timeouts
+
+```swift
+// ✅ Good - timeout for network operations
+@AsyncSatisfies(provider: networkProvider, using: RemoteSpec())
+var isEnabled: Bool?
+
+func check() async {
+ do {
+ let result = try await withTimeout(seconds: 10) {
+ try await $isEnabled.evaluate()
+ }
+ } catch {
+ // Handle timeout
+ }
+}
+
+// ❌ Avoid - no timeout on network operations
+let result = try await $isEnabled.evaluate() // Could hang indefinitely
+```
+
+### Provide Fallback Behavior
+
+```swift
+// ✅ Good - fallback on error
+@AsyncSatisfies(provider: apiProvider, using: RemoteConfigSpec())
+var useNewFeature: Bool?
+
+func configureFeature() async {
+ do {
+ let enabled = try await $useNewFeature.evaluate()
+ if enabled {
+ enableNewFeature()
+ }
+ } catch {
+ // Use safe default
+ useStableFeature()
+ logError(error)
+ }
+}
+```
+
+### Cache Results When Appropriate
+
+```swift
+// ✅ Good - cache for expensive operations
+class ConfigManager {
+ @AsyncSatisfies(provider: networkProvider, using: ConfigSpec())
+ var isFeatureEnabled: Bool?
+
+ private var cachedResult: Bool?
+ private var lastFetch: Date?
+ private let cacheTimeout: TimeInterval = 300 // 5 minutes
+
+ func checkFeature() async throws -> Bool {
+ // Use cache if valid
+ if let cached = cachedResult,
+ let lastFetch = lastFetch,
+ Date().timeIntervalSince(lastFetch) < cacheTimeout {
+ return cached
+ }
+
+ // Fetch fresh value
+ let result = try await $isFeatureEnabled.evaluate()
+ cachedResult = result
+ lastFetch = Date()
+ return result
+ }
+}
+```
+
+### Handle Errors Gracefully
+
+```swift
+// ✅ Good - specific error handling
+func checkAccess() async -> AccessLevel {
+ do {
+ let hasAccess = try await $premiumAccess.evaluate()
+ return hasAccess ? .premium : .free
+ } catch is NetworkError {
+ // Network issues - use cached or safe default
+ return .free
+ } catch is AuthenticationError {
+ // Auth issues - require re-login
+ return .requiresAuth
+ } catch {
+ // Unknown errors - safe default
+ logError(error)
+ return .free
+ }
+}
+```
+
+## Performance Considerations
+
+- **Async Overhead**: Async context fetching and evaluation has inherent overhead
+- **No Automatic Evaluation**: No performance cost unless explicitly evaluated
+- **No Caching**: Context fetched fresh on each `evaluate()` call
+- **Network Latency**: Network-based specs may have significant latency
+- **Error Handling Cost**: Minimal overhead for error propagation
+- **Threading**: Async evaluation can run on any thread, managed by Swift concurrency
+
+Consider caching at the provider or application level for frequently accessed async values.
+
+## Topics
+
+### Property Values
+
+- ``wrappedValue``
+
+### Async Evaluation
+
+- ``Projection``
+- ``projectedValue``
+
+### Property Values
+
+- ``wrappedValue``
+
+## See Also
+
+-
+-
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/AsyncSpecification.md b/Sources/SpecificationCore/Documentation.docc/AsyncSpecification.md
new file mode 100644
index 0000000..20537d3
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/AsyncSpecification.md
@@ -0,0 +1,418 @@
+# ``SpecificationCore/AsyncSpecification``
+
+A protocol for specifications that require asynchronous evaluation.
+
+## Overview
+
+The `AsyncSpecification` protocol extends the Specification Pattern to support async operations such as network requests, database queries, file I/O, or any evaluation that needs to be performed asynchronously. It follows the same pattern as ``Specification`` but leverages Swift's async/await for non-blocking evaluation.
+
+### Key Benefits
+
+- **Non-Blocking Evaluation**: Perform expensive operations without blocking the calling thread
+- **Error Handling**: Built-in support for throwing errors during evaluation
+- **Async/Await Support**: Leverage Swift's modern concurrency features
+- **Type Safety**: Generic associated type ensures compile-time correctness
+- **Composability**: Works with standard specifications through bridging
+
+### When to Use AsyncSpecification
+
+Use `AsyncSpecification` when you need to:
+- Query remote APIs or services
+- Access databases or file systems
+- Perform long-running computations
+- Coordinate multiple async data sources
+- Evaluate specifications that depend on I/O
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+struct User {
+ let id: String
+ let email: String
+}
+
+// Define an async specification
+struct SubscriptionActiveSpec: AsyncSpecification {
+ let apiClient: SubscriptionAPI
+
+ func isSatisfiedBy(_ user: User) async throws -> Bool {
+ let subscription = try await apiClient.fetchSubscription(userId: user.id)
+ return subscription.isActive && !subscription.isExpired
+ }
+}
+
+// Use the async specification
+let spec = SubscriptionActiveSpec(apiClient: client)
+let user = User(id: "123", email: "user@example.com")
+
+do {
+ let isActive = try await spec.isSatisfiedBy(user)
+ if isActive {
+ print("User has active subscription")
+ }
+} catch {
+ print("Error checking subscription: \(error)")
+}
+```
+
+## Bridging Synchronous Specifications
+
+Convert any synchronous ``Specification`` to async using ``AnyAsyncSpecification``:
+
+```swift
+struct LocalUserSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.email.contains("@")
+ }
+}
+
+// Bridge to async
+let asyncSpec = AnyAsyncSpecification(LocalUserSpec())
+
+let result = try await asyncSpec.isSatisfiedBy(user) // Works in async context
+```
+
+## Using with Property Wrappers
+
+Combine async specifications with the ``AsyncSatisfies`` property wrapper:
+
+```swift
+struct FeatureViewModel {
+ let user: User
+
+ @AsyncSatisfies(using: SubscriptionActiveSpec(apiClient: client))
+ var hasActiveSubscription: Bool
+
+ init(user: User) {
+ self.user = user
+ _hasActiveSubscription = AsyncSatisfies(
+ using: SubscriptionActiveSpec(apiClient: client),
+ with: user
+ )
+ }
+
+ func checkAccess() async throws -> Bool {
+ try await $hasActiveSubscription.evaluateAsync()
+ }
+}
+
+let viewModel = FeatureViewModel(user: user)
+let hasAccess = try await viewModel.checkAccess()
+```
+
+## Network-Based Specifications
+
+Query remote APIs to evaluate specifications:
+
+```swift
+struct RemoteFeatureFlagSpec: AsyncSpecification {
+ let flagKey: String
+ let apiClient: FeatureFlagAPI
+
+ func isSatisfiedBy(_ context: EvaluationContext) async throws -> Bool {
+ let flags = try await apiClient.fetchFlags(userId: context.userId)
+ return flags[flagKey] == true
+ }
+}
+
+// Use with remote feature flags
+let premiumFeaturesSpec = RemoteFeatureFlagSpec(
+ flagKey: "premium_features",
+ apiClient: client
+)
+
+if try await premiumFeaturesSpec.isSatisfiedBy(context) {
+ // Enable premium features
+}
+```
+
+## Database Query Specifications
+
+Access databases asynchronously:
+
+```swift
+struct UserHasPurchasedSpec: AsyncSpecification {
+ let database: Database
+ let productId: String
+
+ func isSatisfiedBy(_ user: User) async throws -> Bool {
+ let purchases = try await database.fetchPurchases(userId: user.id)
+ return purchases.contains { $0.productId == productId }
+ }
+}
+
+// Check purchase history
+let hasProVersion = UserHasPurchasedSpec(
+ database: db,
+ productId: "pro_version"
+)
+
+if try await hasProVersion.isSatisfiedBy(user) {
+ // Grant pro features
+}
+```
+
+## Coordinating Multiple Async Sources
+
+Use async/let for concurrent evaluation:
+
+```swift
+struct EligibilityCheckSpec: AsyncSpecification {
+ let userService: UserService
+ let billingService: BillingService
+ let complianceService: ComplianceService
+
+ func isSatisfiedBy(_ user: User) async throws -> Bool {
+ // Fetch all data concurrently
+ async let profile = userService.fetchProfile(user.id)
+ async let billing = billingService.checkStatus(user.id)
+ async let compliance = complianceService.verifyUser(user.id)
+
+ // Wait for all results
+ let (userProfile, billingStatus, complianceStatus) =
+ try await (profile, billing, compliance)
+
+ // Evaluate combined criteria
+ return userProfile.isVerified &&
+ billingStatus.isGoodStanding &&
+ complianceStatus.isCompliant
+ }
+}
+```
+
+## Type-Erased Async Specifications
+
+Use ``AnyAsyncSpecification`` for flexibility:
+
+```swift
+// Store different async specs together
+let asyncChecks: [AnyAsyncSpecification] = [
+ AnyAsyncSpecification(SubscriptionActiveSpec(apiClient: client)),
+ AnyAsyncSpecification(UserHasPurchasedSpec(database: db, productId: "premium")),
+ AnyAsyncSpecification { user in
+ // Custom async logic
+ try await customCheck(user)
+ }
+]
+
+// Evaluate all checks
+for check in asyncChecks {
+ let result = try await check.isSatisfiedBy(user)
+ print("Check result: \(result)")
+}
+```
+
+## Creating from Closures
+
+Create async specifications from closures:
+
+```swift
+let delayedSpec = AnyAsyncSpecification { user in
+ // Simulate network delay
+ try await Task.sleep(nanoseconds: 100_000_000) // 0.1 seconds
+ return user.email.contains("@verified.com")
+}
+
+let isVerified = try await delayedSpec.isSatisfiedBy(user)
+```
+
+## Error Handling Patterns
+
+### Try-Catch Pattern
+
+```swift
+do {
+ let isEligible = try await spec.isSatisfiedBy(user)
+ if isEligible {
+ // Proceed with action
+ }
+} catch let error as NetworkError {
+ print("Network error: \(error.localizedDescription)")
+} catch {
+ print("Unexpected error: \(error)")
+}
+```
+
+### Optional Result Pattern
+
+```swift
+func evaluateSpec(_ user: User) async -> Bool {
+ do {
+ return try await spec.isSatisfiedBy(user)
+ } catch {
+ print("Error evaluating spec: \(error)")
+ return false // Safe default
+ }
+}
+```
+
+### Result Type Pattern
+
+```swift
+func evaluateSpec(_ user: User) async -> Result {
+ do {
+ let result = try await spec.isSatisfiedBy(user)
+ return .success(result)
+ } catch {
+ return .failure(error)
+ }
+}
+
+let result = await evaluateSpec(user)
+switch result {
+case .success(let isEligible):
+ print("Eligible: \(isEligible)")
+case .failure(let error):
+ print("Error: \(error)")
+}
+```
+
+## Timeout Handling
+
+Add timeouts to async specification evaluation:
+
+```swift
+struct TimeoutAsyncSpec: AsyncSpecification {
+ let wrapped: S
+ let timeout: Duration
+
+ func isSatisfiedBy(_ candidate: S.T) async throws -> Bool {
+ try await withThrowingTaskGroup(of: Bool.self) { group in
+ group.addTask {
+ try await self.wrapped.isSatisfiedBy(candidate)
+ }
+ group.addTask {
+ try await Task.sleep(for: self.timeout)
+ throw TimeoutError()
+ }
+
+ let result = try await group.next()!
+ group.cancelAll()
+ return result
+ }
+ }
+}
+
+// Use with timeout
+let timedSpec = TimeoutAsyncSpec(
+ wrapped: RemoteFeatureFlagSpec(flagKey: "feature", apiClient: client),
+ timeout: .seconds(5)
+)
+```
+
+## Caching Async Results
+
+Cache expensive async evaluations:
+
+```swift
+actor CachedAsyncSpec: AsyncSpecification where S.T: Hashable {
+ let wrapped: S
+ var cache: [S.T: Bool] = [:]
+
+ init(_ spec: S) {
+ self.wrapped = spec
+ }
+
+ func isSatisfiedBy(_ candidate: S.T) async throws -> Bool {
+ if let cached = cache[candidate] {
+ return cached
+ }
+
+ let result = try await wrapped.isSatisfiedBy(candidate)
+ cache[candidate] = result
+ return result
+ }
+
+ func clearCache() {
+ cache.removeAll()
+ }
+}
+
+// Use cached spec
+let cachedSpec = CachedAsyncSpec(
+ SubscriptionActiveSpec(apiClient: client)
+)
+
+let result1 = try await cachedSpec.isSatisfiedBy(user) // Fetches from API
+let result2 = try await cachedSpec.isSatisfiedBy(user) // Returns cached value
+```
+
+## Best Practices
+
+### Use Structured Concurrency
+
+```swift
+// ✅ Good - use async/let for concurrent operations
+async let check1 = spec1.isSatisfiedBy(user)
+async let check2 = spec2.isSatisfiedBy(user)
+let (result1, result2) = try await (check1, check2)
+
+// ❌ Avoid - sequential when could be concurrent
+let result1 = try await spec1.isSatisfiedBy(user)
+let result2 = try await spec2.isSatisfiedBy(user)
+```
+
+### Handle Errors Appropriately
+
+```swift
+// ✅ Good - specific error handling
+do {
+ return try await spec.isSatisfiedBy(user)
+} catch is NetworkError {
+ return false // Safe default for network errors
+} catch is DatabaseError {
+ throw // Propagate database errors
+}
+
+// ❌ Avoid - swallowing all errors silently
+let result = (try? await spec.isSatisfiedBy(user)) ?? false
+```
+
+### Provide Cancellation Support
+
+```swift
+// ✅ Good - check for cancellation
+func isSatisfiedBy(_ user: User) async throws -> Bool {
+ try Task.checkCancellation()
+
+ let data = try await fetchData(for: user)
+
+ try Task.checkCancellation()
+
+ return processData(data)
+}
+```
+
+## Performance Considerations
+
+- **Concurrent Evaluation**: Use async/let to evaluate multiple async specs concurrently
+- **Caching**: Cache results of expensive async operations when appropriate
+- **Timeouts**: Add timeouts to prevent indefinite waiting
+- **Cancellation**: Support task cancellation for long-running operations
+- **Resource Management**: Clean up resources properly in async contexts
+
+## Topics
+
+### Essential Protocol
+
+- ``isSatisfiedBy(_:)``
+
+### Type Erasure
+
+- ``AnyAsyncSpecification``
+
+### Property Wrappers
+
+- ``AsyncSatisfies``
+
+### Bridging
+
+- ``AnyAsyncSpecification``
+
+## See Also
+
+-
+- ``AsyncSatisfies``
+- ``AnyAsyncSpecification``
diff --git a/Sources/SpecificationCore/Documentation.docc/AutoContextMacro.md b/Sources/SpecificationCore/Documentation.docc/AutoContextMacro.md
new file mode 100644
index 0000000..c0508a8
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/AutoContextMacro.md
@@ -0,0 +1,701 @@
+# @AutoContext Macro
+
+A macro that automatically provides context provider conformance and enables convenient async specification evaluation.
+
+## Overview
+
+The `@AutoContext` macro eliminates boilerplate by automatically injecting the necessary code for specifications to work with ``DefaultContextProvider``. It adds conformance to `AutoContextSpecification`, provides a context provider property, and when combined with ``specs``, adds an `isSatisfied` computed property for convenient async evaluation.
+
+### Key Benefits
+
+- **Eliminates Boilerplate**: No manual context provider wiring needed
+- **Auto-Conformance**: Automatically conforms to `AutoContextSpecification`
+- **Convenience Property**: Adds `isSatisfied` async property when used with ``specs``
+- **Default Provider**: Uses `DefaultContextProvider.shared` automatically
+- **Type-Safe**: Compile-time type checking for context providers
+- **Future-Proof**: Designed to support custom providers in future versions
+
+### When to Use @AutoContext
+
+Use `@AutoContext` when you need to:
+- Create specifications that work with the default context provider
+- Enable convenient async evaluation without explicit provider passing
+- Reduce boilerplate in specification definitions
+- Build reusable specification types that automatically have provider access
+- Combine with ``specs`` macro for maximum convenience
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+// Without @AutoContext - manual provider management
+struct PremiumUserSpec: Specification {
+ typealias T = EvaluationContext
+
+ func isSatisfiedBy(_ candidate: EvaluationContext) -> Bool {
+ return candidate.flag(for: "premium_subscription")
+ }
+
+ // Manual usage requires provider
+ static func evaluate() -> Bool {
+ let context = DefaultContextProvider.shared.currentContext()
+ return Self().isSatisfiedBy(context)
+ }
+}
+
+// With @AutoContext - automatic provider access
+@AutoContext
+@specs(
+ FeatureFlagSpec(flagKey: "premium_subscription")
+)
+struct PremiumUserSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+// Convenient async evaluation
+if try await PremiumUserSpec().isSatisfied {
+ enablePremiumFeatures()
+}
+```
+
+## How @AutoContext Works
+
+The macro generates provider-related boilerplate automatically:
+
+```swift
+@AutoContext
+struct MySpec: Specification {
+ typealias T = EvaluationContext
+ // Your specification logic...
+}
+
+// Expands to add:
+struct MySpec: Specification {
+ typealias T = EvaluationContext
+
+ // Generated by @AutoContext:
+ public typealias Provider = DefaultContextProvider
+ public static var contextProvider: DefaultContextProvider {
+ DefaultContextProvider.shared
+ }
+
+ // Your specification logic...
+}
+```
+
+When combined with ``specs``, it also adds:
+
+```swift
+@AutoContext
+@specs(SomeSpec())
+struct MySpec: Specification {
+ typealias T = EvaluationContext
+}
+
+// Also generates:
+public var isSatisfied: Bool {
+ get async throws {
+ let ctx = try await Self.contextProvider.currentContextAsync()
+ return composite.isSatisfiedBy(ctx)
+ }
+}
+```
+
+## Usage Examples
+
+### Basic Auto-Context Specification
+
+```swift
+@AutoContext
+@specs(
+ FeatureFlagSpec(flagKey: "new_feature_enabled")
+)
+struct NewFeatureSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+// Usage with isSatisfied
+let spec = NewFeatureSpec()
+if try await spec.isSatisfied {
+ showNewFeature()
+}
+```
+
+### Complex Eligibility Specification
+
+```swift
+@AutoContext
+@specs(
+ TimeSinceEventSpec(eventKey: "user_registered", days: 30),
+ FeatureFlagSpec(flagKey: "email_verified"),
+ MaxCountSpec.dailyLimit("premium_actions", limit: 100),
+ CooldownIntervalSpec(eventKey: "last_violation", days: 90)
+)
+struct PremiumEligibilitySpec: Specification {
+ typealias T = EvaluationContext
+}
+
+func checkEligibility() async throws -> Bool {
+ let spec = PremiumEligibilitySpec()
+ return try await spec.isSatisfied
+}
+```
+
+### Feature Gate with Auto-Context
+
+```swift
+@AutoContext
+@specs(
+ FeatureFlagSpec(flagKey: "experimental_ui"),
+ UserSegmentSpec(expectedSegment: .beta)
+)
+struct ExperimentalUIAccessSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+func loadAppInterface() async {
+ do {
+ if try await ExperimentalUIAccessSpec().isSatisfied {
+ loadExperimentalUI()
+ } else {
+ loadStandardUI()
+ }
+ } catch {
+ // Handle error - fall back to standard UI
+ loadStandardUI()
+ }
+}
+```
+
+### API Access Control
+
+```swift
+@AutoContext
+@specs(
+ MaxCountSpec.dailyLimit("api_calls", limit: 10000),
+ MaxCountSpec(counterKey: "hourly_calls", maximumCount: 1000),
+ FeatureFlagSpec(flagKey: "api_enabled"),
+ CooldownIntervalSpec(eventKey: "rate_limit_violation", minutes: 5)
+)
+struct APIAccessSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+func canMakeAPICall() async throws -> Bool {
+ return try await APIAccessSpec().isSatisfied
+}
+
+func performAPICall() async throws {
+ guard try await canMakeAPICall() else {
+ throw APIError.rateLimitExceeded
+ }
+
+ // Make API call
+ let response = try await apiClient.request()
+
+ // Track usage
+ DefaultContextProvider.shared.incrementCounter("api_calls")
+ DefaultContextProvider.shared.incrementCounter("hourly_calls")
+
+ return response
+}
+```
+
+## Real-World Examples
+
+### Subscription Access Manager
+
+```swift
+@AutoContext
+@specs(
+ FeatureFlagSpec(flagKey: "subscription_active"),
+ DateComparisonSpec(
+ eventKey: "subscription_start",
+ comparison: .before,
+ date: Date()
+ ),
+ MaxCountSpec(counterKey: "payment_failures", maximumCount: 0)
+)
+struct ActiveSubscriptionSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+@AutoContext
+@specs(
+ FeatureFlagSpec(flagKey: "subscription_cancelled").not(),
+ DateComparisonSpec(
+ eventKey: "subscription_end",
+ comparison: .after,
+ date: Date()
+ )
+)
+struct ValidSubscriptionPeriodSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+class SubscriptionManager {
+ func checkAccess() async throws -> AccessLevel {
+ let isActive = try await ActiveSubscriptionSpec().isSatisfied
+ let isValid = try await ValidSubscriptionPeriodSpec().isSatisfied
+
+ if isActive && isValid {
+ return .full
+ } else if isValid {
+ return .gracePeriod
+ } else {
+ return .none
+ }
+ }
+}
+```
+
+### Content Moderation System
+
+```swift
+@AutoContext
+@specs(
+ MaxCountSpec(counterKey: "content_warnings", maximumCount: 3),
+ MaxCountSpec(counterKey: "community_reports", maximumCount: 10),
+ TimeSinceEventSpec(eventKey: "last_suspension", days: 90),
+ FeatureFlagSpec(flagKey: "account_suspended").not()
+)
+struct CanPostContentSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+@AutoContext
+@specs(
+ MaxCountSpec(counterKey: "moderation_flags", maximumCount: 1),
+ CooldownIntervalSpec(eventKey: "last_flagged_post", hours: 24),
+ FeatureFlagSpec(flagKey: "auto_moderation_enabled").not()
+)
+struct RequiresModerationSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+class ContentManager {
+ func submitPost(_ content: String) async throws {
+ let canPost = try await CanPostContentSpec().isSatisfied
+
+ guard canPost else {
+ throw ContentError.postingRestricted
+ }
+
+ let needsModeration = try await RequiresModerationSpec().isSatisfied
+
+ if needsModeration {
+ await queueForModeration(content)
+ } else {
+ await publishImmediately(content)
+ }
+ }
+}
+```
+
+### Feature Rollout Controller
+
+```swift
+@AutoContext
+@specs(
+ FeatureFlagSpec(flagKey: "feature_enabled"),
+ DateRangeSpec(start: rolloutStart, end: rolloutEnd),
+ UserSegmentSpec(expectedSegment: .beta)
+)
+struct BetaFeatureSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+@AutoContext
+@specs(
+ FeatureFlagSpec(flagKey: "feature_enabled"),
+ DateComparisonSpec(eventKey: "general_availability_date", comparison: .after, date: Date())
+)
+struct GAFeatureSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+class FeatureRolloutManager {
+ func determineFeatureAvailability() async throws -> FeatureAvailability {
+ let isBetaUser = try await BetaFeatureSpec().isSatisfied
+ let isGA = try await GAFeatureSpec().isSatisfied
+
+ if isGA {
+ return .generallyAvailable
+ } else if isBetaUser {
+ return .betaAccess
+ } else {
+ return .unavailable
+ }
+ }
+
+ func enableFeatureIfAvailable() async {
+ do {
+ let availability = try await determineFeatureAvailability()
+
+ switch availability {
+ case .generallyAvailable:
+ enableFeature(withBadge: nil)
+ case .betaAccess:
+ enableFeature(withBadge: "BETA")
+ case .unavailable:
+ showComingSoonMessage()
+ }
+ } catch {
+ logError("Feature availability check failed: \(error)")
+ showComingSoonMessage()
+ }
+ }
+}
+```
+
+### Multi-Tier Access Control
+
+```swift
+@AutoContext
+@specs(
+ FeatureFlagSpec(flagKey: "free_tier")
+)
+struct FreeTierSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+@AutoContext
+@specs(
+ FeatureFlagSpec(flagKey: "premium_subscription"),
+ MaxCountSpec(counterKey: "premium_features_used", maximumCount: 100)
+)
+struct PremiumTierSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+@AutoContext
+@specs(
+ FeatureFlagSpec(flagKey: "enterprise_subscription"),
+ FeatureFlagSpec(flagKey: "dedicated_support")
+)
+struct EnterpriseTierSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+class TierManager {
+ func getCurrentTier() async throws -> UserTier {
+ if try await EnterpriseTierSpec().isSatisfied {
+ return .enterprise
+ } else if try await PremiumTierSpec().isSatisfied {
+ return .premium
+ } else if try await FreeTierSpec().isSatisfied {
+ return .free
+ } else {
+ return .none
+ }
+ }
+
+ func getFeatureAccess() async throws -> [Feature] {
+ let tier = try await getCurrentTier()
+
+ switch tier {
+ case .enterprise:
+ return Feature.allCases
+ case .premium:
+ return Feature.premiumFeatures
+ case .free:
+ return Feature.freeFeatures
+ case .none:
+ return []
+ }
+ }
+}
+```
+
+## Combining with Property Wrappers
+
+Use @AutoContext specifications with property wrappers for clean integration:
+
+```swift
+@AutoContext
+@specs(
+ FeatureFlagSpec(flagKey: "new_ui_enabled")
+)
+struct NewUISpec: Specification {
+ typealias T = EvaluationContext
+}
+
+// Use with @Satisfies
+@Satisfies(using: NewUISpec())
+var shouldShowNewUI: Bool
+
+// Or evaluate directly
+func checkNewUI() async throws -> Bool {
+ return try await NewUISpec().isSatisfied
+}
+```
+
+## SwiftUI Integration
+
+Use @AutoContext specifications in SwiftUI views:
+
+```swift
+@AutoContext
+@specs(
+ FeatureFlagSpec(flagKey: "premium_features"),
+ TimeSinceEventSpec(eventKey: "subscription_start", days: 0)
+)
+struct PremiumAccessSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+struct ContentView: View {
+ @State private var hasPremiumAccess = false
+ @State private var isLoading = true
+
+ var body: some View {
+ Group {
+ if isLoading {
+ ProgressView("Checking access...")
+ } else if hasPremiumAccess {
+ PremiumContentView()
+ } else {
+ FreeContentView()
+ }
+ }
+ .task {
+ await checkAccess()
+ }
+ }
+
+ func checkAccess() async {
+ isLoading = true
+ defer { isLoading = false }
+
+ do {
+ hasPremiumAccess = try await PremiumAccessSpec().isSatisfied
+ } catch {
+ hasPremiumAccess = false
+ print("Access check failed: \(error)")
+ }
+ }
+}
+```
+
+## Error Handling
+
+Handle errors from async specification evaluation:
+
+```swift
+@AutoContext
+@specs(
+ FeatureFlagSpec(flagKey: "feature_enabled")
+)
+struct FeatureSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+func checkFeature() async {
+ do {
+ let isEnabled = try await FeatureSpec().isSatisfied
+
+ if isEnabled {
+ enableFeature()
+ } else {
+ disableFeature()
+ }
+ } catch {
+ // Handle error - use safe default
+ disableFeature()
+ logError("Feature check failed: \(error)")
+ }
+}
+```
+
+## Testing
+
+Test @AutoContext specifications using the standard provider:
+
+```swift
+func testAutoContextSpec() async throws {
+ @AutoContext
+ @specs(
+ FeatureFlagSpec(flagKey: "test_feature")
+ )
+ struct TestSpec: Specification {
+ typealias T = EvaluationContext
+ }
+
+ // Set up test state
+ DefaultContextProvider.shared.setFlag("test_feature", to: true)
+
+ // Test using isSatisfied
+ let spec = TestSpec()
+ let result = try await spec.isSatisfied
+
+ XCTAssertTrue(result)
+
+ // Test with flag disabled
+ DefaultContextProvider.shared.setFlag("test_feature", to: false)
+ let result2 = try await spec.isSatisfied
+
+ XCTAssertFalse(result2)
+}
+```
+
+## Future Enhancements
+
+The @AutoContext macro is designed to support future features:
+
+### Custom Provider Types (Planned)
+
+```swift
+// Future: Custom provider type
+@AutoContext(CustomProvider.self)
+struct MySpec: Specification {
+ typealias T = CustomContext
+}
+```
+
+### SwiftUI Environment Integration (Planned)
+
+```swift
+// Future: Environment-based provider
+@AutoContext(environment)
+struct MySpec: Specification {
+ typealias T = EvaluationContext
+}
+```
+
+### Provider Inference (Planned)
+
+```swift
+// Future: Infer provider from context type
+@AutoContext(infer)
+struct MySpec: Specification {
+ typealias T = CustomContext
+}
+```
+
+**Note**: These features emit informative warnings when used, indicating they are recognized but not yet implemented.
+
+## Best Practices
+
+### Always Use with @specs
+
+```swift
+// ✅ Good - combined with @specs
+@AutoContext
+@specs(
+ FeatureFlagSpec(flagKey: "enabled")
+)
+struct MySpec: Specification {
+ typealias T = EvaluationContext
+}
+
+// ❌ Less useful - @AutoContext alone doesn't add much value
+@AutoContext
+struct MySpec: Specification {
+ typealias T = EvaluationContext
+
+ func isSatisfiedBy(_ candidate: EvaluationContext) -> Bool {
+ // Manual implementation
+ return candidate.flag(for: "enabled")
+ }
+}
+```
+
+### Handle Async Errors Appropriately
+
+```swift
+// ✅ Good - proper error handling
+func checkAccess() async -> Bool {
+ do {
+ return try await AccessSpec().isSatisfied
+ } catch {
+ logError(error)
+ return false // Safe default
+ }
+}
+
+// ❌ Avoid - ignoring errors
+func checkAccess() async -> Bool {
+ return (try? await AccessSpec().isSatisfied) ?? false
+ // Lost error information
+}
+```
+
+### Use Descriptive Specification Names
+
+```swift
+// ✅ Good - clear purpose
+@AutoContext
+@specs(...)
+struct PremiumContentAccessSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+// ❌ Avoid - unclear naming
+@AutoContext
+@specs(...)
+struct Spec1: Specification {
+ typealias T = EvaluationContext
+}
+```
+
+## Performance Considerations
+
+- **Shared Provider**: Uses singleton `DefaultContextProvider.shared` (no allocation overhead)
+- **Async Evaluation**: `isSatisfied` property uses async context fetching
+- **Compile-Time**: Macro expansion happens at compile time (no runtime overhead)
+- **Type Erasure**: Minimal overhead from `AnySpecification` usage
+
+## Comparison with Manual Provider Management
+
+### Manual Provider Management
+
+```swift
+struct ManualSpec: Specification {
+ typealias T = EvaluationContext
+
+ func isSatisfiedBy(_ candidate: EvaluationContext) -> Bool {
+ // Implementation...
+ return true
+ }
+
+ // Manual evaluation helper
+ static func evaluate() -> Bool {
+ let context = DefaultContextProvider.shared.currentContext()
+ return Self().isSatisfiedBy(context)
+ }
+}
+
+// Usage
+if ManualSpec.evaluate() {
+ // Do something
+}
+```
+
+### With @AutoContext Macro
+
+```swift
+@AutoContext
+@specs(...)
+struct AutoSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+// Usage - cleaner async API
+if try await AutoSpec().isSatisfied {
+ // Do something
+}
+```
+
+## Topics
+
+### Related Macros
+
+-
+
+## See Also
+
+-
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/ContextProviding.md b/Sources/SpecificationCore/Documentation.docc/ContextProviding.md
new file mode 100644
index 0000000..ab1f88b
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/ContextProviding.md
@@ -0,0 +1,450 @@
+# ``SpecificationCore/ContextProviding``
+
+A protocol for types that provide evaluation context to specifications.
+
+## Overview
+
+The `ContextProviding` protocol abstracts context creation and retrieval for specification evaluation. This enables dependency injection, testing with mock contexts, and dynamic context management without tightly coupling specifications to specific context implementations.
+
+### Key Benefits
+
+- **Dependency Injection**: Inject different context providers for production vs testing
+- **Abstraction**: Decouple specifications from context storage mechanisms
+- **Testability**: Easily provide mock contexts for unit testing
+- **Flexibility**: Switch context providers without changing specification code
+- **Async Support**: Built-in async context retrieval methods
+
+### When to Use ContextProviding
+
+Use `ContextProviding` when you need to:
+- Provide runtime context to specifications (feature flags, counters, timestamps)
+- Support different context sources (memory, database, network)
+- Enable dependency injection for testability
+- Create reusable context infrastructure
+- Abstract context retrieval mechanisms
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+// Define your context type
+struct AppContext {
+ let userId: String
+ let featureFlags: [String: Bool]
+ let sessionStart: Date
+}
+
+// Create a context provider
+struct AppContextProvider: ContextProviding {
+ func currentContext() -> AppContext {
+ AppContext(
+ userId: UserSession.current.userId,
+ featureFlags: FeatureFlagManager.shared.allFlags(),
+ sessionStart: UserSession.current.startTime
+ )
+ }
+}
+
+// Use with specifications
+let provider = AppContextProvider()
+let context = provider.currentContext()
+
+// Specifications can now use this context
+let spec = FeatureFlagSpec(flagKey: "new_ui")
+let isEnabled = spec.isSatisfiedBy(context)
+```
+
+## Built-in Context: EvaluationContext
+
+SpecificationCore provides ``EvaluationContext`` as a standard context type:
+
+```swift
+// Use the default context provider
+let provider = DefaultContextProvider.shared
+
+// Set some context data
+provider.setFlag("premium_user", value: true)
+provider.setCounter("login_attempts", value: 3)
+provider.recordEvent("last_login")
+
+// Get current context
+let context = provider.currentContext()
+
+// Use with specifications
+let spec = MaxCountSpec(
+ counterKey: "login_attempts",
+ maximumCount: 5
+)
+let canRetry = spec.isSatisfiedBy(context)
+```
+
+## Generic Context Provider
+
+Create context providers from closures:
+
+```swift
+// Simple closure-based provider
+let provider = GenericContextProvider {
+ EvaluationContext(userId: UserSession.currentUserId)
+}
+
+let context = provider.currentContext()
+```
+
+## Static Context Provider
+
+Provide a fixed context for testing or simple use cases:
+
+```swift
+// Create a static context for testing
+let testContext = EvaluationContext(userId: "test-user-123")
+let provider = StaticContextProvider(testContext)
+
+// Always returns the same context
+let context1 = provider.currentContext()
+let context2 = provider.currentContext()
+// context1 === context2 (same instance)
+```
+
+## Async Context Retrieval
+
+Context providers support async retrieval for remote or database-backed contexts:
+
+```swift
+struct RemoteContextProvider: ContextProviding {
+ let apiClient: APIClient
+
+ func currentContext() -> EvaluationContext {
+ // Synchronous fallback
+ EvaluationContext(userId: "default")
+ }
+
+ func currentContextAsync() async throws -> EvaluationContext {
+ let userData = try await apiClient.fetchUserData()
+ return EvaluationContext(
+ userId: userData.id,
+ flags: userData.featureFlags,
+ counters: userData.usageCounters
+ )
+ }
+}
+
+// Use async retrieval
+let provider = RemoteContextProvider(apiClient: client)
+let context = try await provider.currentContextAsync()
+```
+
+## Creating Specifications with Providers
+
+Use context providers to create specifications:
+
+```swift
+let provider = DefaultContextProvider.shared
+
+// Create a specification using the provider
+let spec = provider.predicate { context, user in
+ context.flag(for: "premium_users_only") == true &&
+ user.subscriptionTier == "premium"
+}
+
+// Or create a more complex specification
+let dynamicSpec = provider.specification { context in
+ if context.flag(for: "use_new_rules") == true {
+ return AnySpecification(NewEligibilityRules())
+ } else {
+ return AnySpecification(LegacyEligibilityRules())
+ }
+}
+```
+
+## Testing with Mock Providers
+
+Create mock providers for unit testing:
+
+```swift
+// Use the built-in mock provider
+let mockProvider = MockContextProvider()
+mockProvider.setFlag("test_feature", value: true)
+mockProvider.setCounter("attempts", value: 2)
+
+// Inject into your code
+class UserService {
+ let contextProvider: any ContextProviding
+
+ init(contextProvider: any ContextProviding = DefaultContextProvider.shared) {
+ self.contextProvider = contextProvider
+ }
+
+ func checkEligibility(_ user: User) -> Bool {
+ let context = contextProvider.currentContext()
+ let spec = EligibilitySpec()
+ return spec.isSatisfiedBy((user, context))
+ }
+}
+
+// Test with mock provider
+let service = UserService(contextProvider: mockProvider)
+let isEligible = service.checkEligibility(testUser)
+```
+
+## Custom Context Types
+
+Create custom context types for domain-specific needs:
+
+```swift
+struct OrderContext {
+ let orderId: String
+ let customerId: String
+ let orderTotal: Decimal
+ let createdAt: Date
+ let items: [OrderItem]
+}
+
+struct OrderContextProvider: ContextProviding {
+ let database: Database
+
+ func currentContext() -> OrderContext {
+ // Fetch current order context
+ let orderId = CurrentOrderSession.orderId
+ let order = database.fetchOrder(orderId)
+
+ return OrderContext(
+ orderId: order.id,
+ customerId: order.customerId,
+ orderTotal: order.total,
+ createdAt: order.createdAt,
+ items: order.items
+ )
+ }
+}
+
+// Use with order-specific specifications
+struct MinimumOrderSpec: Specification {
+ let minimumTotal: Decimal
+
+ func isSatisfiedBy(_ context: OrderContext) -> Bool {
+ context.orderTotal >= minimumTotal
+ }
+}
+
+let provider = OrderContextProvider(database: db)
+let context = provider.currentContext()
+let meetsMinimum = MinimumOrderSpec(minimumTotal: 50.00).isSatisfiedBy(context)
+```
+
+## Environment-Specific Providers
+
+Create different providers for different environments:
+
+```swift
+protocol AppContextProviding: ContextProviding where Context == EvaluationContext {}
+
+struct ProductionContextProvider: AppContextProviding {
+ func currentContext() -> EvaluationContext {
+ EvaluationContext(
+ userId: UserDefaults.standard.string(forKey: "userId") ?? "",
+ flags: RemoteConfigManager.shared.flags,
+ counters: AnalyticsManager.shared.counters
+ )
+ }
+}
+
+struct StagingContextProvider: AppContextProviding {
+ func currentContext() -> EvaluationContext {
+ EvaluationContext(
+ userId: "staging-user",
+ flags: ["all_features": true], // Enable all features in staging
+ counters: [:]
+ )
+ }
+}
+
+// Configure based on environment
+#if DEBUG
+let contextProvider: any AppContextProviding = StagingContextProvider()
+#else
+let contextProvider: any AppContextProviding = ProductionContextProvider()
+#endif
+```
+
+## Thread-Safe Providers
+
+Ensure thread safety when context can be accessed concurrently:
+
+```swift
+actor ThreadSafeContextProvider: ContextProviding {
+ private var cachedContext: EvaluationContext?
+ private let refreshInterval: TimeInterval
+
+ init(refreshInterval: TimeInterval = 60) {
+ self.refreshInterval = refreshInterval
+ }
+
+ func currentContext() -> EvaluationContext {
+ // Note: Actor-isolated, must be called with await in async context
+ if let cached = cachedContext {
+ return cached
+ }
+
+ let context = buildContext()
+ cachedContext = context
+ return context
+ }
+
+ private func buildContext() -> EvaluationContext {
+ EvaluationContext(
+ userId: fetchUserId(),
+ flags: fetchFlags(),
+ counters: fetchCounters()
+ )
+ }
+}
+```
+
+## Scoped Context Providers
+
+Create context providers for specific scopes:
+
+```swift
+struct ScopedContextProvider: ContextProviding {
+ let scope: String
+ let baseProvider: DefaultContextProvider
+
+ func currentContext() -> EvaluationContext {
+ var context = baseProvider.currentContext()
+
+ // Add scope-specific data
+ context.metadata["scope"] = scope
+ context.metadata["scope_timestamp"] = Date()
+
+ return context
+ }
+}
+
+// Use for different parts of your app
+let checkoutProvider = ScopedContextProvider(
+ scope: "checkout",
+ baseProvider: .shared
+)
+
+let profileProvider = ScopedContextProvider(
+ scope: "profile",
+ baseProvider: .shared
+)
+```
+
+## Combining Multiple Providers
+
+Merge contexts from multiple providers:
+
+```swift
+struct CompositeProvider: ContextProviding {
+ let providers: [any ContextProviding]
+
+ func currentContext() -> EvaluationContext {
+ var merged = EvaluationContext()
+
+ for provider in providers {
+ let context = provider.currentContext()
+ merged.merge(with: context)
+ }
+
+ return merged
+ }
+}
+
+// Combine user, feature, and analytics contexts
+let provider = CompositeProvider(providers: [
+ UserContextProvider(),
+ FeatureFlagProvider(),
+ AnalyticsProvider()
+])
+```
+
+## Best Practices
+
+### Use Dependency Injection
+
+```swift
+// ✅ Good - inject provider for testability
+class FeatureService {
+ let contextProvider: any ContextProviding
+
+ init(contextProvider: any ContextProviding = DefaultContextProvider.shared) {
+ self.contextProvider = contextProvider
+ }
+}
+
+// ❌ Avoid - hard-coded provider
+class FeatureService {
+ func checkFeature() {
+ let context = DefaultContextProvider.shared.currentContext() // Hard to test
+ }
+}
+```
+
+### Provide Default Implementations
+
+```swift
+// ✅ Good - default parameter for production use
+init(contextProvider: any ContextProviding = DefaultContextProvider.shared) {
+ self.contextProvider = contextProvider
+}
+
+// Easy to use in production
+let service = FeatureService() // Uses default
+
+// Easy to test
+let service = FeatureService(contextProvider: mockProvider)
+```
+
+### Cache Contexts When Appropriate
+
+```swift
+// ✅ Good - cache expensive context creation
+class CachingProvider: ContextProviding {
+ private var cache: EvaluationContext?
+ private var cacheTime: Date?
+ private let cacheTimeout: TimeInterval = 60
+
+ func currentContext() -> EvaluationContext {
+ if let cached = cache,
+ let time = cacheTime,
+ Date().timeIntervalSince(time) < cacheTimeout {
+ return cached
+ }
+
+ let context = buildExpensiveContext()
+ cache = context
+ cacheTime = Date()
+ return context
+ }
+}
+```
+
+## Performance Considerations
+
+- **Lazy Context Creation**: Don't create context until needed
+- **Caching**: Cache contexts when creation is expensive
+- **Thread Safety**: Ensure providers are thread-safe if used concurrently
+- **Async Methods**: Use async methods for I/O-bound context creation
+- **Resource Cleanup**: Clean up resources in context providers when appropriate
+
+## Topics
+
+### Essential Protocol
+
+- ``currentContext()``
+- ``currentContextAsync()``
+
+### Generic Providers
+
+- ``GenericContextProvider``
+- ``StaticContextProvider``
+
+## See Also
+
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/CooldownIntervalSpec.md b/Sources/SpecificationCore/Documentation.docc/CooldownIntervalSpec.md
new file mode 100644
index 0000000..d2da2f6
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/CooldownIntervalSpec.md
@@ -0,0 +1,638 @@
+# ``SpecificationCore/CooldownIntervalSpec``
+
+A specification that ensures enough time has passed since the last occurrence of an event.
+
+## Overview
+
+`CooldownIntervalSpec` implements cooldown periods for actions like showing banners, notifications, or any time-sensitive operations that shouldn't happen too frequently. It evaluates to true when sufficient time has elapsed since an event was last recorded.
+
+### Key Benefits
+
+- **Time-Based Throttling**: Prevent actions from occurring too frequently
+- **Flexible Time Units**: Create cooldowns in seconds, minutes, hours, or days
+- **Event Tracking**: Works with ``EvaluationContext`` event timestamps
+- **Utility Methods**: Calculate remaining time and next allowed execution
+- **Advanced Patterns**: Exponential backoff and time-of-day based cooldowns
+
+### When to Use CooldownIntervalSpec
+
+Use `CooldownIntervalSpec` when you need to:
+- Prevent notifications from appearing too frequently
+- Implement rate limiting for user actions
+- Control banner or popup display frequency
+- Enforce minimum time between retries
+- Throttle API calls or expensive operations
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+// Set up context and record event
+let provider = DefaultContextProvider.shared
+provider.recordEvent("last_notification")
+
+// Create 1-hour cooldown spec
+let notificationCooldown = CooldownIntervalSpec(
+ eventKey: "last_notification",
+ hours: 1
+)
+
+// Use with property wrapper
+@Satisfies(using: notificationCooldown)
+var canShowNotification: Bool
+
+if canShowNotification {
+ showNotification()
+ provider.recordEvent("last_notification") // Reset cooldown
+}
+```
+
+## Creating CooldownIntervalSpec
+
+### Basic Creation
+
+```swift
+// Create with TimeInterval (seconds)
+let cooldown1 = CooldownIntervalSpec(
+ eventKey: "last_action",
+ cooldownInterval: 3600 // 1 hour in seconds
+)
+
+// Or use time unit convenience initializers
+let cooldown2 = CooldownIntervalSpec(
+ eventKey: "last_action",
+ seconds: 60
+)
+```
+
+### Time Unit Initializers
+
+```swift
+// Seconds
+let shortCooldown = CooldownIntervalSpec(
+ eventKey: "button_click",
+ seconds: 5
+)
+
+// Minutes
+let mediumCooldown = CooldownIntervalSpec(
+ eventKey: "form_submit",
+ minutes: 15
+)
+
+// Hours
+let longCooldown = CooldownIntervalSpec(
+ eventKey: "daily_reminder",
+ hours: 24
+)
+
+// Days
+let veryLongCooldown = CooldownIntervalSpec(
+ eventKey: "weekly_survey",
+ days: 7
+)
+```
+
+### Convenience Factories
+
+```swift
+// Common time periods
+let hourly = CooldownIntervalSpec.hourly("api_call")
+let daily = CooldownIntervalSpec.daily("notification")
+let weekly = CooldownIntervalSpec.weekly("newsletter")
+let monthly = CooldownIntervalSpec.monthly("report")
+
+// Custom interval
+let custom = CooldownIntervalSpec.custom(
+ "custom_event",
+ interval: 90 // 90 seconds
+)
+```
+
+## How It Works
+
+The specification checks if enough time has passed since the event:
+
+```swift
+let cooldown = CooldownIntervalSpec(eventKey: "last_shown", hours: 1)
+
+// Event never occurred: satisfied ✅ (no cooldown needed)
+// Event 30 minutes ago: NOT satisfied ❌ (still on cooldown)
+// Event 1 hour ago: satisfied ✅ (cooldown expired)
+// Event 2 hours ago: satisfied ✅ (cooldown long expired)
+```
+
+## Usage Examples
+
+### Notification Throttling
+
+```swift
+let provider = DefaultContextProvider.shared
+
+// Create notification cooldown (1 hour)
+let notificationCooldown = CooldownIntervalSpec(
+ eventKey: "last_notification_shown",
+ hours: 1
+)
+
+@Satisfies(using: notificationCooldown)
+var canShowNotification: Bool
+
+func showImportantNotification(_ message: String) {
+ guard canShowNotification else {
+ print("Notification on cooldown")
+ return
+ }
+
+ displayNotification(message)
+ provider.recordEvent("last_notification_shown")
+}
+```
+
+### Banner Display Control
+
+```swift
+// Show promotional banner maximum once per day
+let bannerCooldown = CooldownIntervalSpec.daily("promo_banner_shown")
+
+@Satisfies(using: bannerCooldown)
+var shouldShowBanner: Bool
+
+struct ContentView: View {
+ var body: some View {
+ VStack {
+ if shouldShowBanner {
+ PromoBanner()
+ .onTapGesture {
+ DefaultContextProvider.shared
+ .recordEvent("promo_banner_shown")
+ }
+ }
+ MainContent()
+ }
+ }
+}
+```
+
+### Retry Logic
+
+```swift
+// Minimum 5 minutes between retry attempts
+let retryCooldown = CooldownIntervalSpec(
+ eventKey: "last_retry_attempt",
+ minutes: 5
+)
+
+@Satisfies(using: retryCooldown)
+var canRetry: Bool
+
+func retryFailedOperation() async {
+ guard canRetry else {
+ showError("Please wait before retrying")
+ return
+ }
+
+ await performOperation()
+ DefaultContextProvider.shared.recordEvent("last_retry_attempt")
+}
+```
+
+### API Rate Limiting
+
+```swift
+// Minimum 10 seconds between API calls
+let apiCooldown = CooldownIntervalSpec(
+ eventKey: "last_api_call",
+ seconds: 10
+)
+
+@Satisfies(using: apiCooldown)
+var canCallAPI: Bool
+
+func fetchData() async throws -> Data {
+ guard canCallAPI else {
+ throw APIError.tooManyRequests
+ }
+
+ let data = try await performAPICall()
+ DefaultContextProvider.shared.recordEvent("last_api_call")
+ return data
+}
+```
+
+## Utility Methods
+
+### Remaining Cooldown Time
+
+```swift
+let cooldown = CooldownIntervalSpec(eventKey: "last_action", minutes: 30)
+let context = DefaultContextProvider.shared.currentContext()
+
+// Get remaining time in seconds
+let remaining = cooldown.remainingCooldownTime(in: context)
+
+if remaining > 0 {
+ print("Wait \(Int(remaining)) seconds before next action")
+} else {
+ print("Action available now")
+}
+```
+
+### Check if Cooldown is Active
+
+```swift
+let cooldown = CooldownIntervalSpec.hourly("feature_use")
+let context = provider.currentContext()
+
+if cooldown.isCooldownActive(in: context) {
+ print("Feature is on cooldown")
+} else {
+ print("Feature is available")
+}
+```
+
+### Next Allowed Time
+
+```swift
+let cooldown = CooldownIntervalSpec(eventKey: "survey_shown", days: 7)
+let context = provider.currentContext()
+
+if let nextTime = cooldown.nextAllowedTime(in: context) {
+ let formatter = DateFormatter()
+ formatter.dateStyle = .medium
+ formatter.timeStyle = .short
+
+ print("Available again at: \(formatter.string(from: nextTime))")
+} else {
+ print("Available now")
+}
+```
+
+## Advanced Patterns
+
+### Exponential Backoff
+
+Increase cooldown time with each occurrence:
+
+```swift
+// Base 60 seconds, doubles with each attempt
+let backoffSpec = CooldownIntervalSpec.exponentialBackoff(
+ eventKey: "failed_login",
+ baseInterval: 60, // 1 minute
+ counterKey: "login_attempts",
+ maxInterval: 3600 // Max 1 hour
+)
+
+// Attempt 1: 60 seconds
+// Attempt 2: 120 seconds
+// Attempt 3: 240 seconds
+// Attempt 4: 480 seconds
+// Attempt 5: 960 seconds
+// Attempt 6+: 3600 seconds (capped)
+
+@Satisfies(using: backoffSpec)
+var canAttemptLogin: Bool
+```
+
+### Time-of-Day Based Cooldowns
+
+Different cooldowns for day vs. night:
+
+```swift
+// 30 minutes during day, 2 hours at night
+let timeBasedCooldown = CooldownIntervalSpec.timeOfDayBased(
+ eventKey: "notification",
+ daytimeInterval: .minutes(30),
+ nighttimeInterval: .hours(2),
+ daytimeHours: 8...22 // 8 AM to 10 PM
+)
+
+// Notification at 3 PM: 30-minute cooldown
+// Notification at 11 PM: 2-hour cooldown
+```
+
+## Composition
+
+Combine with other cooldowns or specifications:
+
+### Multiple Cooldowns (AND)
+
+```swift
+// Both cooldowns must be satisfied
+let strictCooldown = CooldownIntervalSpec.hourly("feature_a")
+ .and(CooldownIntervalSpec.daily("feature_b"))
+
+// Feature A: must be > 1 hour since last use
+// Feature B: must be > 1 day since last use
+// Both must be satisfied
+```
+
+### Multiple Cooldowns (OR)
+
+```swift
+// Either cooldown can be satisfied
+let flexibleCooldown = CooldownIntervalSpec.weekly("method_a")
+ .or(CooldownIntervalSpec.monthly("method_b"))
+
+// Can proceed if EITHER weekly OR monthly cooldown expired
+```
+
+### With Other Specifications
+
+```swift
+// Cooldown AND feature flag
+let gatedFeature = CooldownIntervalSpec.daily("premium_feature")
+ .and(FeatureFlagSpec(flagKey: "premium_enabled"))
+
+// Must pass cooldown AND have feature enabled
+```
+
+## Real-World Examples
+
+### Survey Prompts
+
+```swift
+struct SurveyPromptManager {
+ let provider = DefaultContextProvider.shared
+
+ // Show survey once per month
+ let surveyCooldown = CooldownIntervalSpec.monthly("survey_shown")
+
+ // Also require minimum app usage
+ let usageRequirement = TimeSinceEventSpec(
+ eventKey: "app_first_launch",
+ days: 7
+ )
+
+ var shouldShowSurvey: Bool {
+ let context = provider.currentContext()
+ return surveyCooldown.isSatisfiedBy(context) &&
+ usageRequirement.isSatisfiedBy(context)
+ }
+
+ func showSurvey() {
+ guard shouldShowSurvey else { return }
+
+ presentSurveyModal()
+ provider.recordEvent("survey_shown")
+ }
+}
+```
+
+### Push Notification Management
+
+```swift
+class NotificationManager {
+ let provider = DefaultContextProvider.shared
+
+ // Different cooldowns for different notification types
+ let criticalCooldown = CooldownIntervalSpec(eventKey: "critical_alert", minutes: 5)
+ let standardCooldown = CooldownIntervalSpec(eventKey: "standard_notif", hours: 1)
+ let marketingCooldown = CooldownIntervalSpec(eventKey: "marketing_notif", days: 1)
+
+ func canSend(notification: Notification) -> Bool {
+ let context = provider.currentContext()
+
+ switch notification.type {
+ case .critical:
+ return criticalCooldown.isSatisfiedBy(context)
+ case .standard:
+ return standardCooldown.isSatisfiedBy(context)
+ case .marketing:
+ return marketingCooldown.isSatisfiedBy(context)
+ }
+ }
+
+ func send(_ notification: Notification) {
+ guard canSend(notification: notification) else {
+ print("Notification throttled")
+ return
+ }
+
+ deliverNotification(notification)
+
+ // Record event based on type
+ let eventKey: String
+ switch notification.type {
+ case .critical: eventKey = "critical_alert"
+ case .standard: eventKey = "standard_notif"
+ case .marketing: eventKey = "marketing_notif"
+ }
+
+ provider.recordEvent(eventKey)
+ }
+}
+```
+
+### Feature Usage Throttling
+
+```swift
+class PremiumFeatureGate {
+ let provider = DefaultContextProvider.shared
+
+ // Premium users: 1-hour cooldown
+ // Free users: 24-hour cooldown
+ func getCooldown(for tier: UserTier) -> CooldownIntervalSpec {
+ switch tier {
+ case .premium:
+ return .hourly("ai_generation")
+ case .free:
+ return .daily("ai_generation")
+ }
+ }
+
+ func canUseFeature(user: User) -> Bool {
+ let cooldown = getCooldown(for: user.tier)
+ let context = provider.currentContext()
+ return cooldown.isSatisfiedBy(context)
+ }
+
+ func useFeature(user: User) async throws -> Result {
+ guard canUseFeature(user: user) else {
+ let cooldown = getCooldown(for: user.tier)
+ let remaining = cooldown.remainingCooldownTime(
+ in: provider.currentContext()
+ )
+
+ throw FeatureError.onCooldown(
+ remainingSeconds: Int(remaining)
+ )
+ }
+
+ let result = try await performFeature()
+ provider.recordEvent("ai_generation")
+ return result
+ }
+}
+```
+
+## Testing
+
+Use ``MockContextProvider`` to test cooldown behavior:
+
+```swift
+func testCooldownNotExpired() {
+ // Event occurred 30 minutes ago
+ let provider = MockContextProvider.cooldownScenario(
+ eventKey: "last_action",
+ timeSinceEvent: 1800 // 30 minutes
+ )
+
+ let spec = CooldownIntervalSpec(eventKey: "last_action", hours: 1)
+
+ // Should be on cooldown (30 min < 1 hour)
+ XCTAssertFalse(spec.isSatisfiedBy(provider.currentContext()))
+}
+
+func testCooldownExpired() {
+ // Event occurred 2 hours ago
+ let provider = MockContextProvider.cooldownScenario(
+ eventKey: "last_action",
+ timeSinceEvent: 7200 // 2 hours
+ )
+
+ let spec = CooldownIntervalSpec(eventKey: "last_action", hours: 1)
+
+ // Should be available (2 hours > 1 hour)
+ XCTAssertTrue(spec.isSatisfiedBy(provider.currentContext()))
+}
+
+func testNoEventRecorded() {
+ // No event recorded
+ let provider = MockContextProvider()
+
+ let spec = CooldownIntervalSpec.hourly("never_happened")
+
+ // Should be satisfied (no previous event)
+ XCTAssertTrue(spec.isSatisfiedBy(provider.currentContext()))
+}
+
+func testRemainingTime() {
+ let now = Date()
+ let thirtyMinutesAgo = now.addingTimeInterval(-1800)
+
+ let provider = MockContextProvider()
+ .withCurrentDate(now)
+ .withEvent("action", date: thirtyMinutesAgo)
+
+ let spec = CooldownIntervalSpec(eventKey: "action", hours: 1)
+
+ let remaining = spec.remainingCooldownTime(in: provider.currentContext())
+
+ // Should have ~30 minutes remaining (1800 seconds)
+ XCTAssertEqual(remaining, 1800, accuracy: 1.0)
+}
+```
+
+## Best Practices
+
+### Record Events Immediately After Actions
+
+```swift
+// ✅ Good - record event after action completes
+if canShowNotification {
+ showNotification()
+ provider.recordEvent("last_notification")
+}
+
+// ❌ Avoid - recording before action
+provider.recordEvent("last_notification")
+showNotification() // Might fail, but cooldown already started
+```
+
+### Use Appropriate Time Units
+
+```swift
+// ✅ Good - use readable time units
+let hourly = CooldownIntervalSpec(eventKey: "api_call", hours: 1)
+let daily = CooldownIntervalSpec(eventKey: "report", days: 1)
+
+// ❌ Less readable - raw seconds
+let hourly = CooldownIntervalSpec(eventKey: "api_call", seconds: 3600)
+let daily = CooldownIntervalSpec(eventKey: "report", seconds: 86400)
+```
+
+### Provide User Feedback
+
+```swift
+// ✅ Good - inform user of remaining time
+if !canPerformAction {
+ let remaining = cooldown.remainingCooldownTime(in: context)
+ let minutes = Int(remaining / 60)
+ showAlert("Please wait \(minutes) minutes before trying again")
+}
+
+// ❌ Avoid - silent failure
+if !canPerformAction {
+ return // User doesn't know why
+}
+```
+
+### Use Consistent Event Keys
+
+```swift
+// ✅ Good - descriptive, consistent naming
+"last_notification_shown"
+"last_api_call_made"
+"last_password_reset_attempt"
+
+// ❌ Avoid - ambiguous or inconsistent
+"notif"
+"api"
+"reset"
+```
+
+## Performance Considerations
+
+- **Event Lookup**: O(1) dictionary access from context
+- **Date Arithmetic**: Simple subtraction; very fast
+- **No State Mutation**: Read-only evaluation
+- **Missing Events**: Returns true (satisfied) if event not found
+- **Utility Methods**: Calculate on-demand; no caching overhead
+
+## Topics
+
+### Creating Specifications
+
+- ``init(eventKey:cooldownInterval:)``
+- ``init(eventKey:seconds:)``
+- ``init(eventKey:minutes:)``
+- ``init(eventKey:hours:)``
+- ``init(eventKey:days:)``
+
+### Convenience Factories
+
+- ``hourly(_:)``
+- ``daily(_:)``
+- ``weekly(_:)``
+- ``monthly(_:)``
+- ``custom(_:interval:)``
+
+### Utility Methods
+
+- ``remainingCooldownTime(in:)``
+- ``isCooldownActive(in:)``
+- ``nextAllowedTime(in:)``
+
+### Advanced Patterns
+
+- ``exponentialBackoff(eventKey:baseInterval:counterKey:maxInterval:)``
+- ``timeOfDayBased(eventKey:daytimeInterval:nighttimeInterval:daytimeHours:)``
+
+### Composition
+
+- ``and(_:)``
+- ``or(_:)``
+
+### Properties
+
+- ``eventKey``
+- ``cooldownInterval``
+
+## See Also
+
+-
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/DateComparisonSpec.md b/Sources/SpecificationCore/Documentation.docc/DateComparisonSpec.md
new file mode 100644
index 0000000..2367f16
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/DateComparisonSpec.md
@@ -0,0 +1,503 @@
+# ``SpecificationCore/DateComparisonSpec``
+
+A specification that compares a stored event date to a reference date.
+
+## Overview
+
+`DateComparisonSpec` checks whether an event occurred before or after a specific reference date. This is useful for determining if events happened within certain timeframes, validating chronological ordering, or implementing date-based eligibility rules.
+
+### Key Benefits
+
+- **Event Chronology**: Verify when events occurred relative to dates
+- **Simple Comparisons**: Before/after logic with clear semantics
+- **Event-Based**: Works with ``EvaluationContext`` event timestamps
+- **Eligibility Checking**: Determine if events meet date requirements
+- **Deadline Enforcement**: Check if events occurred before deadlines
+
+### When to Use DateComparisonSpec
+
+Use `DateComparisonSpec` when you need to:
+- Check if an event occurred before a deadline
+- Verify events happened after a start date
+- Enforce chronological ordering of events
+- Validate event timing for eligibility
+- Compare event dates to milestones
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+// Record when user registered
+let provider = DefaultContextProvider.shared
+provider.recordEvent("user_registered")
+
+// Check if registration was before a cutoff date
+let cutoffDate = DateComponents(
+ calendar: .current,
+ year: 2025,
+ month: 12,
+ day: 31
+).date!
+
+let eligibilitySpec = DateComparisonSpec(
+ eventKey: "user_registered",
+ comparison: .before,
+ date: cutoffDate
+)
+
+let context = provider.currentContext()
+
+if eligibilitySpec.isSatisfiedBy(context) {
+ grantEarlyAdopterBenefits()
+}
+```
+
+## Creating DateComparisonSpec
+
+```swift
+// Check if event occurred before a date
+let beforeSpec = DateComparisonSpec(
+ eventKey: "action_taken",
+ comparison: .before,
+ date: referenceDate
+)
+
+// Check if event occurred after a date
+let afterSpec = DateComparisonSpec(
+ eventKey: "action_taken",
+ comparison: .after,
+ date: referenceDate
+)
+```
+
+## Comparison Types
+
+### Before Comparison
+
+Event date must be strictly less than reference date:
+
+```swift
+let deadline = Date(timeIntervalSince1970: 2000)
+let spec = DateComparisonSpec(
+ eventKey: "submission",
+ comparison: .before,
+ date: deadline
+)
+
+// Event at 1500: satisfied ✅ (1500 < 2000)
+// Event at 2000: NOT satisfied ❌ (2000 < 2000 is false)
+// Event at 2500: NOT satisfied ❌ (2500 < 2000 is false)
+```
+
+### After Comparison
+
+Event date must be strictly greater than reference date:
+
+```swift
+let startDate = Date(timeIntervalSince1970: 1000)
+let spec = DateComparisonSpec(
+ eventKey: "enrollment",
+ comparison: .after,
+ date: startDate
+)
+
+// Event at 500: NOT satisfied ❌ (500 > 1000 is false)
+// Event at 1000: NOT satisfied ❌ (1000 > 1000 is false)
+// Event at 1500: satisfied ✅ (1500 > 1000)
+```
+
+## Usage Examples
+
+### Early Registration Benefit
+
+```swift
+// Give benefits to users who registered before Jan 1, 2025
+let cutoffDate = DateComponents(
+ calendar: .current,
+ year: 2025,
+ month: 1,
+ day: 1,
+ hour: 0,
+ minute: 0
+).date!
+
+let earlyUserSpec = DateComparisonSpec(
+ eventKey: "user_registered",
+ comparison: .before,
+ date: cutoffDate
+)
+
+@Satisfies(using: earlyUserSpec)
+var isEarlyAdopter: Bool
+
+if isEarlyAdopter {
+ grantLifetimeDiscount()
+}
+```
+
+### Contest Deadline
+
+```swift
+// Check if submission was before contest deadline
+let contestDeadline = DateComponents(
+ calendar: .current,
+ year: 2025,
+ month: 6,
+ day: 30,
+ hour: 23,
+ minute: 59
+).date!
+
+let validSubmissionSpec = DateComparisonSpec(
+ eventKey: "contest_submission",
+ comparison: .before,
+ date: contestDeadline
+)
+
+func validateSubmission() -> Bool {
+ let context = DefaultContextProvider.shared.currentContext()
+ return validSubmissionSpec.isSatisfiedBy(context)
+}
+```
+
+### Beta Access Gate
+
+```swift
+// Beta opened on a specific date - check if user enrolled after
+let betaStartDate = DateComponents(
+ calendar: .current,
+ year: 2025,
+ month: 3,
+ day: 1
+).date!
+
+let betaEligibilitySpec = DateComparisonSpec(
+ eventKey: "beta_enrollment",
+ comparison: .after,
+ date: betaStartDate
+)
+
+@Satisfies(using: betaEligibilitySpec)
+var enrolledDuringBeta: Bool
+```
+
+### Milestone Verification
+
+```swift
+// Check if milestone was reached after launch date
+let launchDate = DateComponents(
+ calendar: .current,
+ year: 2025,
+ month: 1,
+ day: 15
+).date!
+
+let postLaunchSpec = DateComparisonSpec(
+ eventKey: "milestone_reached",
+ comparison: .after,
+ date: launchDate
+)
+
+func trackPostLaunchMilestone() {
+ let context = DefaultContextProvider.shared.currentContext()
+
+ if postLaunchSpec.isSatisfiedBy(context) {
+ recordAsPostLaunchAchievement()
+ }
+}
+```
+
+## Real-World Examples
+
+### Grandfathered Pricing
+
+```swift
+class PricingManager {
+ let pricingChangeDate = DateComponents(
+ calendar: .current,
+ year: 2025,
+ month: 7,
+ day: 1
+ ).date!
+
+ // Users who subscribed before price change get old pricing
+ lazy var grandfatheredSpec = DateComparisonSpec(
+ eventKey: "subscription_started",
+ comparison: .before,
+ date: pricingChangeDate
+ )
+
+ func getMonthlyPrice(for user: User) -> Decimal {
+ let context = DefaultContextProvider.shared.currentContext()
+
+ if grandfatheredSpec.isSatisfiedBy(context) {
+ return 9.99 // Old pricing
+ } else {
+ return 14.99 // New pricing
+ }
+ }
+}
+```
+
+### Event Attendance Verification
+
+```swift
+struct ConferenceManager {
+ let conferenceDate = DateComponents(
+ calendar: .current,
+ year: 2025,
+ month: 9,
+ day: 15
+ ).date!
+
+ // Check if user registered before conference
+ lazy var preRegistrationSpec = DateComparisonSpec(
+ eventKey: "conference_registration",
+ comparison: .before,
+ date: conferenceDate
+ )
+
+ // Check if user checked in after conference started
+ lazy var attendanceSpec = DateComparisonSpec(
+ eventKey: "conference_checkin",
+ comparison: .after,
+ date: conferenceDate
+ )
+
+ func getAttendanceStatus() -> AttendanceStatus {
+ let context = DefaultContextProvider.shared.currentContext()
+
+ let preRegistered = preRegistrationSpec.isSatisfiedBy(context)
+ let checkedIn = attendanceSpec.isSatisfiedBy(context)
+
+ if preRegistered && checkedIn {
+ return .attended
+ } else if preRegistered {
+ return .registered
+ } else {
+ return .notRegistered
+ }
+ }
+}
+```
+
+### Warranty Validation
+
+```swift
+class WarrantyManager {
+ func createWarrantySpec(
+ purchaseEventKey: String,
+ warrantyMonths: Int
+ ) -> DateComparisonSpec {
+ let purchaseDate = DefaultContextProvider.shared
+ .getEvent(purchaseEventKey) ?? Date()
+
+ let expirationDate = Calendar.current.date(
+ byAdding: .month,
+ value: warrantyMonths,
+ to: purchaseDate
+ )!
+
+ // Warranty valid if current date is before expiration
+ return DateComparisonSpec(
+ eventKey: purchaseEventKey,
+ comparison: .before,
+ date: expirationDate
+ )
+ }
+
+ func isWarrantyValid(for product: Product) -> Bool {
+ let spec = createWarrantySpec(
+ purchaseEventKey: "purchase_\(product.id)",
+ warrantyMonths: 12
+ )
+
+ let context = DefaultContextProvider.shared.currentContext()
+ return spec.isSatisfiedBy(context)
+ }
+}
+```
+
+## Missing Event Behavior
+
+If the event doesn't exist, the specification returns `false`:
+
+```swift
+let spec = DateComparisonSpec(
+ eventKey: "never_recorded",
+ comparison: .before,
+ date: someDate
+)
+
+let context = DefaultContextProvider.shared.currentContext()
+
+// Returns false because event doesn't exist
+spec.isSatisfiedBy(context) // false
+```
+
+## Testing
+
+Test date comparisons with ``MockContextProvider``:
+
+```swift
+func testEventBefore() {
+ let eventDate = Date(timeIntervalSince1970: 1000)
+ let referenceDate = Date(timeIntervalSince1970: 2000)
+
+ let provider = MockContextProvider()
+ .withEvent("action", date: eventDate)
+ .withCurrentDate(Date())
+
+ let spec = DateComparisonSpec(
+ eventKey: "action",
+ comparison: .before,
+ date: referenceDate
+ )
+
+ // Event at 1000 is before 2000
+ XCTAssertTrue(spec.isSatisfiedBy(provider.currentContext()))
+}
+
+func testEventAfter() {
+ let eventDate = Date(timeIntervalSince1970: 2000)
+ let referenceDate = Date(timeIntervalSince1970: 1000)
+
+ let provider = MockContextProvider()
+ .withEvent("action", date: eventDate)
+
+ let spec = DateComparisonSpec(
+ eventKey: "action",
+ comparison: .after,
+ date: referenceDate
+ )
+
+ // Event at 2000 is after 1000
+ XCTAssertTrue(spec.isSatisfiedBy(provider.currentContext()))
+}
+
+func testMissingEvent() {
+ let provider = MockContextProvider()
+
+ let spec = DateComparisonSpec(
+ eventKey: "never_happened",
+ comparison: .before,
+ date: Date()
+ )
+
+ // Should return false (no event)
+ XCTAssertFalse(spec.isSatisfiedBy(provider.currentContext()))
+}
+
+func testEventAtBoundary() {
+ let date = Date(timeIntervalSince1970: 1000)
+
+ let provider = MockContextProvider()
+ .withEvent("action", date: date)
+
+ // Before comparison with same date
+ let beforeSpec = DateComparisonSpec(
+ eventKey: "action",
+ comparison: .before,
+ date: date
+ )
+ XCTAssertFalse(beforeSpec.isSatisfiedBy(provider.currentContext()))
+
+ // After comparison with same date
+ let afterSpec = DateComparisonSpec(
+ eventKey: "action",
+ comparison: .after,
+ date: date
+ )
+ XCTAssertFalse(afterSpec.isSatisfiedBy(provider.currentContext()))
+}
+```
+
+## Best Practices
+
+### Record Events at the Right Time
+
+```swift
+// ✅ Good - record event when it actually happens
+func submitEntry() {
+ performSubmission()
+ DefaultContextProvider.shared.recordEvent("contest_submission")
+}
+
+// ❌ Avoid - recording before action completes
+func submitEntry() {
+ DefaultContextProvider.shared.recordEvent("contest_submission")
+ performSubmission() // Might fail
+}
+```
+
+### Use Descriptive Event Keys
+
+```swift
+// ✅ Good - clear, specific keys
+"user_registered"
+"subscription_started"
+"contest_submission"
+
+// ❌ Avoid - ambiguous keys
+"event1"
+"date"
+"timestamp"
+```
+
+### Consider Boundary Cases
+
+```swift
+// ✅ Good - handle exact equality explicitly
+// Use .before for "must happen before deadline"
+// Use .after for "must happen after start"
+
+// ❌ Avoid - assuming equal dates satisfy spec
+// Both .before and .after return false for equal dates
+```
+
+### Validate Event Exists
+
+```swift
+// ✅ Good - check if event exists first
+let provider = DefaultContextProvider.shared
+
+if provider.getEvent("important_event") != nil {
+ let spec = DateComparisonSpec(
+ eventKey: "important_event",
+ comparison: .before,
+ date: deadline
+ )
+ // Use spec
+}
+
+// Or handle false result appropriately
+let result = spec.isSatisfiedBy(context)
+if !result {
+ // Could be false because event doesn't exist
+ // Or because comparison failed
+}
+```
+
+## Performance Considerations
+
+- **Event Lookup**: O(1) dictionary access
+- **Date Comparison**: Simple comparison operator
+- **No Computation**: No complex date arithmetic
+- **Missing Events**: Fast path returns false immediately
+
+## Topics
+
+### Creating Specifications
+
+- ``init(eventKey:comparison:date:)``
+
+### Comparison Types
+
+- ``Comparison``
+
+## See Also
+
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/DateRangeSpec.md b/Sources/SpecificationCore/Documentation.docc/DateRangeSpec.md
new file mode 100644
index 0000000..db14a73
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/DateRangeSpec.md
@@ -0,0 +1,540 @@
+# ``SpecificationCore/DateRangeSpec``
+
+A specification that checks if the current date falls within an inclusive date range.
+
+## Overview
+
+`DateRangeSpec` evaluates to true when the current date in the ``EvaluationContext`` is within the specified start and end dates (inclusive). This is useful for implementing time-limited campaigns, seasonal features, or any functionality that should only be active during a specific time period.
+
+### Key Benefits
+
+- **Time-Limited Features**: Enable/disable features during specific periods
+- **Campaign Management**: Control promotional campaigns with dates
+- **Seasonal Content**: Show content only during relevant seasons
+- **Event Windows**: Enforce event start and end times
+- **Simple API**: Straightforward date range checking
+
+### When to Use DateRangeSpec
+
+Use `DateRangeSpec` when you need to:
+- Run promotional campaigns during specific dates
+- Enable seasonal features or content
+- Restrict functionality to event windows
+- Implement time-limited offers
+- Show holiday-specific content
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+// Define campaign dates
+let campaignStart = DateComponents(
+ calendar: .current,
+ year: 2025,
+ month: 12,
+ day: 1
+).date!
+
+let campaignEnd = DateComponents(
+ calendar: .current,
+ year: 2025,
+ month: 12,
+ day: 31
+).date!
+
+// Create spec for December campaign
+let holidayCampaignSpec = DateRangeSpec(
+ start: campaignStart,
+ end: campaignEnd
+)
+
+// Use with context
+let context = DefaultContextProvider.shared.currentContext()
+
+if holidayCampaignSpec.isSatisfiedBy(context) {
+ showHolidayPromotion()
+}
+```
+
+## Creating DateRangeSpec
+
+```swift
+// Basic creation with start and end dates
+let spec = DateRangeSpec(
+ start: startDate,
+ end: endDate
+)
+
+// The range is inclusive: start <= currentDate <= end
+```
+
+## How It Works
+
+The specification checks if current date is within the range:
+
+```swift
+let start = Date(timeIntervalSince1970: 1000)
+let end = Date(timeIntervalSince1970: 2000)
+let spec = DateRangeSpec(start: start, end: end)
+
+// Current date = 900: NOT satisfied ❌ (before start)
+// Current date = 1000: satisfied ✅ (at start)
+// Current date = 1500: satisfied ✅ (in middle)
+// Current date = 2000: satisfied ✅ (at end)
+// Current date = 2100: NOT satisfied ❌ (after end)
+```
+
+## Usage Examples
+
+### Promotional Campaign
+
+```swift
+// Black Friday campaign: Nov 24-27, 2025
+let blackFridayStart = DateComponents(
+ calendar: .current,
+ year: 2025,
+ month: 11,
+ day: 24,
+ hour: 0,
+ minute: 0
+).date!
+
+let blackFridayEnd = DateComponents(
+ calendar: .current,
+ year: 2025,
+ month: 11,
+ day: 27,
+ hour: 23,
+ minute: 59
+).date!
+
+let blackFridaySpec = DateRangeSpec(
+ start: blackFridayStart,
+ end: blackFridayEnd
+)
+
+@Satisfies(using: blackFridaySpec)
+var isBlackFridayActive: Bool
+
+if isBlackFridayActive {
+ applyBlackFridayDiscounts()
+}
+```
+
+### Seasonal Content
+
+```swift
+// Summer content: June 1 - August 31
+let summerStart = DateComponents(
+ calendar: .current,
+ year: Calendar.current.component(.year, from: Date()),
+ month: 6,
+ day: 1
+).date!
+
+let summerEnd = DateComponents(
+ calendar: .current,
+ year: Calendar.current.component(.year, from: Date()),
+ month: 8,
+ day: 31,
+ hour: 23,
+ minute: 59
+).date!
+
+let summerSpec = DateRangeSpec(start: summerStart, end: summerEnd)
+
+struct ContentView: View {
+ @Satisfies(using: summerSpec)
+ var isSummerSeason: Bool
+
+ var body: some View {
+ if isSummerSeason {
+ SummerThemeView()
+ } else {
+ DefaultThemeView()
+ }
+ }
+}
+```
+
+### Limited-Time Feature
+
+```swift
+// Beta feature available for 2 weeks
+let betaStart = Date()
+let betaEnd = Date().addingTimeInterval(14 * 86400) // 14 days
+
+let betaSpec = DateRangeSpec(start: betaStart, end: betaEnd)
+
+@Satisfies(using: betaSpec)
+var isBetaActive: Bool
+
+func accessBetaFeature() {
+ guard isBetaActive else {
+ showExpiredMessage()
+ return
+ }
+
+ showBetaFeature()
+}
+```
+
+### Event Window
+
+```swift
+// Conference dates: March 15-17, 2025
+let conferenceStart = DateComponents(
+ calendar: .current,
+ year: 2025,
+ month: 3,
+ day: 15,
+ hour: 9,
+ minute: 0
+).date!
+
+let conferenceEnd = DateComponents(
+ calendar: .current,
+ year: 2025,
+ month: 3,
+ day: 17,
+ hour: 18,
+ minute: 0
+).date!
+
+let conferenceSpec = DateRangeSpec(
+ start: conferenceStart,
+ end: conferenceEnd
+)
+
+@Satisfies(using: conferenceSpec)
+var isConferenceActive: Bool
+
+if isConferenceActive {
+ enableLiveStreamFeatures()
+}
+```
+
+## Real-World Examples
+
+### Multi-Phase Campaign Manager
+
+```swift
+struct CampaignManager {
+ enum Phase {
+ case prelaunch
+ case earlyBird
+ case regular
+ case lastChance
+ case ended
+
+ var spec: DateRangeSpec? {
+ let calendar = Calendar.current
+ let year = calendar.component(.year, from: Date())
+
+ switch self {
+ case .prelaunch:
+ return DateRangeSpec(
+ start: makeDate(year, 11, 1)!,
+ end: makeDate(year, 11, 14)!
+ )
+ case .earlyBird:
+ return DateRangeSpec(
+ start: makeDate(year, 11, 15)!,
+ end: makeDate(year, 11, 20)!
+ )
+ case .regular:
+ return DateRangeSpec(
+ start: makeDate(year, 11, 21)!,
+ end: makeDate(year, 11, 27)!
+ )
+ case .lastChance:
+ return DateRangeSpec(
+ start: makeDate(year, 11, 28)!,
+ end: makeDate(year, 11, 30)!
+ )
+ case .ended:
+ return nil
+ }
+ }
+
+ private func makeDate(_ year: Int, _ month: Int, _ day: Int) -> Date? {
+ DateComponents(
+ calendar: .current,
+ year: year,
+ month: month,
+ day: day
+ ).date
+ }
+ }
+
+ func getCurrentPhase() -> Phase {
+ let context = DefaultContextProvider.shared.currentContext()
+
+ for phase in [Phase.prelaunch, .earlyBird, .regular, .lastChance] {
+ if let spec = phase.spec, spec.isSatisfiedBy(context) {
+ return phase
+ }
+ }
+
+ return .ended
+ }
+
+ func getDiscount(for phase: Phase) -> Double {
+ switch phase {
+ case .prelaunch: return 0.30
+ case .earlyBird: return 0.25
+ case .regular: return 0.15
+ case .lastChance: return 0.10
+ case .ended: return 0.0
+ }
+ }
+}
+```
+
+### Holiday Feature Manager
+
+```swift
+struct HolidayFeatureManager {
+ struct Holiday {
+ let name: String
+ let spec: DateRangeSpec
+ let theme: Theme
+ }
+
+ let holidays: [Holiday] = [
+ Holiday(
+ name: "Christmas",
+ spec: DateRangeSpec(
+ start: makeDate(12, 20)!,
+ end: makeDate(12, 26)!
+ ),
+ theme: .christmas
+ ),
+ Holiday(
+ name: "New Year",
+ spec: DateRangeSpec(
+ start: makeDate(12, 30)!,
+ end: makeDate(1, 2)!
+ ),
+ theme: .newYear
+ ),
+ Holiday(
+ name: "Valentine's Day",
+ spec: DateRangeSpec(
+ start: makeDate(2, 13)!,
+ end: makeDate(2, 15)!
+ ),
+ theme: .valentines
+ )
+ ]
+
+ func getCurrentHoliday() -> Holiday? {
+ let context = DefaultContextProvider.shared.currentContext()
+
+ return holidays.first { holiday in
+ holiday.spec.isSatisfiedBy(context)
+ }
+ }
+
+ func applyHolidayTheme() {
+ if let holiday = getCurrentHoliday() {
+ ThemeManager.apply(holiday.theme)
+ } else {
+ ThemeManager.apply(.default)
+ }
+ }
+
+ private func makeDate(_ month: Int, _ day: Int) -> Date? {
+ let year = Calendar.current.component(.year, from: Date())
+ return DateComponents(
+ calendar: .current,
+ year: year,
+ month: month,
+ day: day
+ ).date
+ }
+}
+```
+
+### Trial Period Manager
+
+```swift
+class TrialManager {
+ func createTrialSpec(startDate: Date, durationDays: Int) -> DateRangeSpec {
+ let endDate = startDate.addingTimeInterval(
+ TimeInterval(durationDays * 86400)
+ )
+
+ return DateRangeSpec(start: startDate, end: endDate)
+ }
+
+ func checkTrialStatus(user: User) -> TrialStatus {
+ let trialSpec = createTrialSpec(
+ startDate: user.trialStartDate,
+ durationDays: 14
+ )
+
+ let context = DefaultContextProvider.shared.currentContext()
+
+ if trialSpec.isSatisfiedBy(context) {
+ return .active
+ } else {
+ return .expired
+ }
+ }
+}
+```
+
+## Testing
+
+Test date range logic with ``MockContextProvider``:
+
+```swift
+func testWithinRange() {
+ let start = Date(timeIntervalSince1970: 1000)
+ let end = Date(timeIntervalSince1970: 2000)
+ let current = Date(timeIntervalSince1970: 1500)
+
+ let provider = MockContextProvider()
+ .withCurrentDate(current)
+
+ let spec = DateRangeSpec(start: start, end: end)
+
+ // Should be satisfied (1500 is within 1000-2000)
+ XCTAssertTrue(spec.isSatisfiedBy(provider.currentContext()))
+}
+
+func testBeforeRange() {
+ let start = Date(timeIntervalSince1970: 1000)
+ let end = Date(timeIntervalSince1970: 2000)
+ let current = Date(timeIntervalSince1970: 500)
+
+ let provider = MockContextProvider()
+ .withCurrentDate(current)
+
+ let spec = DateRangeSpec(start: start, end: end)
+
+ // Should NOT be satisfied (500 is before 1000)
+ XCTAssertFalse(spec.isSatisfiedBy(provider.currentContext()))
+}
+
+func testAfterRange() {
+ let start = Date(timeIntervalSince1970: 1000)
+ let end = Date(timeIntervalSince1970: 2000)
+ let current = Date(timeIntervalSince1970: 2500)
+
+ let provider = MockContextProvider()
+ .withCurrentDate(current)
+
+ let spec = DateRangeSpec(start: start, end: end)
+
+ // Should NOT be satisfied (2500 is after 2000)
+ XCTAssertFalse(spec.isSatisfiedBy(provider.currentContext()))
+}
+
+func testAtBoundaries() {
+ let start = Date(timeIntervalSince1970: 1000)
+ let end = Date(timeIntervalSince1970: 2000)
+ let spec = DateRangeSpec(start: start, end: end)
+
+ // At start boundary
+ let atStart = MockContextProvider()
+ .withCurrentDate(start)
+ XCTAssertTrue(spec.isSatisfiedBy(atStart.currentContext()))
+
+ // At end boundary
+ let atEnd = MockContextProvider()
+ .withCurrentDate(end)
+ XCTAssertTrue(spec.isSatisfiedBy(atEnd.currentContext()))
+}
+```
+
+## Best Practices
+
+### Use Specific Times for Precision
+
+```swift
+// ✅ Good - includes time components for exact boundaries
+let start = DateComponents(
+ calendar: .current,
+ year: 2025,
+ month: 12,
+ day: 1,
+ hour: 0,
+ minute: 0,
+ second: 0
+).date!
+
+let end = DateComponents(
+ calendar: .current,
+ year: 2025,
+ month: 12,
+ day: 31,
+ hour: 23,
+ minute: 59,
+ second: 59
+).date!
+
+// ❌ Avoid - ambiguous time boundaries
+let start = DateComponents(
+ calendar: .current,
+ year: 2025,
+ month: 12,
+ day: 1
+).date! // Defaults to midnight, but not explicit
+```
+
+### Validate Date Order
+
+```swift
+// ✅ Good - validate that start is before end
+func createDateRangeSpec(start: Date, end: Date) -> DateRangeSpec? {
+ guard start < end else {
+ print("Error: Start date must be before end date")
+ return nil
+ }
+ return DateRangeSpec(start: start, end: end)
+}
+
+// ❌ Avoid - no validation
+let spec = DateRangeSpec(start: endDate, end: startDate) // Wrong order!
+```
+
+### Consider Time Zones
+
+```swift
+// ✅ Good - explicit time zone handling
+var calendar = Calendar.current
+calendar.timeZone = TimeZone(identifier: "America/New_York")!
+
+let start = DateComponents(
+ calendar: calendar,
+ timeZone: TimeZone(identifier: "America/New_York"),
+ year: 2025,
+ month: 12,
+ day: 1
+).date!
+
+// ❌ Avoid - assuming local time zone
+let start = DateComponents(year: 2025, month: 12, day: 1).date!
+```
+
+## Performance Considerations
+
+- **Simple Comparison**: Uses Date's comparable implementation
+- **No Computation**: No complex date arithmetic
+- **Inclusive Range**: Uses Swift's ClosedRange operator
+- **Context Date**: Uses pre-calculated currentDate from context
+
+## Topics
+
+### Creating Specifications
+
+- ``init(start:end:)``
+
+## See Also
+
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/Decides.md b/Sources/SpecificationCore/Documentation.docc/Decides.md
new file mode 100644
index 0000000..69208ca
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Decides.md
@@ -0,0 +1,659 @@
+# ``SpecificationCore/Decides``
+
+A property wrapper that evaluates decision specifications and always returns a non-optional result with fallback.
+
+## Overview
+
+`@Decides` transforms decision-based specifications into declarative properties that always return a typed result. Unlike boolean specifications, decision specifications can return any type (strings, numbers, enums, custom types), making them perfect for routing, tier selection, and configuration management.
+
+### Key Benefits
+
+- **Always Non-Optional**: Guaranteed to return a value using fallback when no specification matches
+- **Priority-Based**: Uses first-match-wins logic for clear precedence rules
+- **Type-Safe Results**: Generic over both context and result types
+- **Projected Value Access**: Check if a specification matched via `$propertyName`
+- **Flexible Initialization**: Multiple patterns including arrays, builders, and custom logic
+- **Composable**: Works with any ``DecisionSpec`` implementation
+
+### When to Use @Decides
+
+Use `@Decides` when you need to:
+- Determine user tier, subscription level, or feature access
+- Select routing paths, content variants, or UI themes
+- Calculate discounts, pricing, or reward values
+- Choose configuration based on multiple conditions
+- Make priority-based decisions with guaranteed results
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+// Determine user tier with fallback
+@Decides([
+ (PremiumMemberSpec(), "premium"),
+ (StandardMemberSpec(), "standard")
+], or: "basic")
+var userTier: String
+
+// Usage
+let features = getFeatures(for: userTier) // Always returns a value
+```
+
+## Creating @Decides
+
+### With Specification-Result Pairs
+
+```swift
+// Array of (Specification, Result) pairs
+@Decides([
+ (PremiumUserSpec(), 25.0), // 25% discount
+ (LoyalCustomerSpec(), 15.0), // 15% discount
+ (FirstTimeUserSpec(), 10.0) // 10% discount
+], or: 0.0) // No discount
+var discountPercentage: Double
+```
+
+### With DecisionSpec Instance
+
+```swift
+let routingSpec = FirstMatchSpec([
+ (MobileUserSpec(), "mobile_route"),
+ (TabletUserSpec(), "tablet_route")
+])
+
+@Decides(using: routingSpec, or: "desktop_route")
+var navigationRoute: String
+```
+
+### With Builder Pattern
+
+```swift
+@Decides(build: { builder in
+ builder
+ .add(VIPUserSpec(), result: "vip_content")
+ .add(PremiumUserSpec(), result: "premium_content")
+ .add(TrialUserSpec(), result: "trial_content")
+}, or: "free_content")
+var contentVariant: String
+```
+
+### With Custom Decision Logic
+
+```swift
+@Decides(decide: { context in
+ let score = context.counter(for: "engagement_score")
+ switch score {
+ case 80...100: return "high_engagement"
+ case 50...79: return "medium_engagement"
+ case 20...49: return "low_engagement"
+ default: return nil // Will use fallback
+ }
+}, or: "no_engagement")
+var engagementLevel: String
+```
+
+### With Default Value
+
+```swift
+// Using wrappedValue for default
+@Decides(wrappedValue: "standard", [
+ (PremiumUserSpec(), "premium"),
+ (BetaUserSpec(), "beta")
+])
+var userType: String
+```
+
+## How It Works
+
+The wrapper evaluates specifications in order and returns the first match:
+
+```swift
+@Decides([
+ (Spec1(), "result1"), // Checked first
+ (Spec2(), "result2"), // Checked second
+ (Spec3(), "result3") // Checked third
+], or: "default") // Used if none match
+
+// Priority matters:
+// 1. If Spec1 matches → returns "result1"
+// 2. Else if Spec2 matches → returns "result2"
+// 3. Else if Spec3 matches → returns "result3"
+// 4. Else → returns "default"
+```
+
+## Usage Examples
+
+### User Tier Selection
+
+```swift
+enum UserTier: String {
+ case enterprise = "enterprise"
+ case premium = "premium"
+ case standard = "standard"
+ case free = "free"
+}
+
+@Decides([
+ (SubscriptionStatusSpec(status: .enterprise), UserTier.enterprise),
+ (SubscriptionStatusSpec(status: .premium), UserTier.premium),
+ (SubscriptionStatusSpec(status: .standard), UserTier.standard)
+], or: .free)
+var currentTier: UserTier
+
+func getFeatureAccess() -> [Feature] {
+ switch currentTier {
+ case .enterprise:
+ return .all
+ case .premium:
+ return .premiumFeatures
+ case .standard:
+ return .standardFeatures
+ case .free:
+ return .basicFeatures
+ }
+}
+```
+
+### Discount Calculation
+
+```swift
+@Decides([
+ (BlackFridaySpec(), 50.0), // 50% off during Black Friday
+ (PremiumMemberSpec(), 25.0), // 25% for premium members
+ (LoyalCustomerSpec(), 15.0), // 15% for loyal customers
+ (FirstPurchaseSpec(), 10.0), // 10% for first purchase
+ (NewsletterSubscriberSpec(), 5.0) // 5% for subscribers
+], or: 0.0)
+var discountPercentage: Double
+
+func calculateFinalPrice(originalPrice: Double) -> Double {
+ return originalPrice * (1.0 - discountPercentage / 100.0)
+}
+```
+
+### Content Routing
+
+```swift
+@Decides([
+ (ABTestVariantASpec(), "variant_a_content"),
+ (ABTestVariantBSpec(), "variant_b_content"),
+ (ABTestVariantCSpec(), "variant_c_content")
+], or: "control_content")
+var experimentContent: String
+
+@Decides([
+ (RegionSpec(region: "EU"), "eu_compliant_content"),
+ (RegionSpec(region: "US"), "us_content"),
+ (RegionSpec(region: "ASIA"), "asia_content")
+], or: "global_content")
+var regionalContent: String
+
+func loadContent() {
+ let experimentVariant = experimentContent
+ let regionalVariant = regionalContent
+
+ display(content: "\(regionalVariant)/\(experimentVariant)")
+}
+```
+
+### Feature Tier Assignment
+
+```swift
+struct FeatureTierManager {
+ enum Tier {
+ case unlimited
+ case professional
+ case starter
+ case free
+
+ var maxProjects: Int {
+ switch self {
+ case .unlimited: return .max
+ case .professional: return 100
+ case .starter: return 10
+ case .free: return 3
+ }
+ }
+
+ var maxStorage: Int { // in GB
+ switch self {
+ case .unlimited: return 1000
+ case .professional: return 100
+ case .starter: return 10
+ case .free: return 1
+ }
+ }
+ }
+
+ @Decides([
+ (SubscriptionStatusSpec(status: .enterprise), Tier.unlimited),
+ (SubscriptionStatusSpec(status: .professional), Tier.professional),
+ (SubscriptionStatusSpec(status: .starter), Tier.starter)
+ ], or: .free)
+ var tier: Tier
+
+ func canCreateProject(currentCount: Int) -> Bool {
+ return currentCount < tier.maxProjects
+ }
+
+ func canUploadFile(currentStorage: Int, fileSize: Int) -> Bool {
+ return (currentStorage + fileSize) <= (tier.maxStorage * 1_000_000_000)
+ }
+}
+```
+
+## Projected Value
+
+The projected value provides access to the optional result without fallback:
+
+```swift
+@Decides([
+ (PremiumUserSpec(), "premium"),
+ (StandardUserSpec(), "standard")
+], or: "free")
+var userType: String
+
+// Regular access always returns a value
+print(userType) // "premium", "standard", or "free"
+
+// Projected value is nil if no specification matched
+if let matchedType = $userType {
+ print("Specification matched with: \(matchedType)")
+ // matchedType is "premium" or "standard"
+} else {
+ print("No specification matched, using fallback")
+ // Used the "free" fallback
+}
+
+// Useful for analytics or debugging
+func trackUserType() {
+ if let matched = $userType {
+ analytics.track("user_type_matched", matched)
+ } else {
+ analytics.track("user_type_defaulted", userType)
+ }
+}
+```
+
+## Real-World Examples
+
+### Pricing Strategy Manager
+
+```swift
+class PricingManager {
+ enum PricingTier {
+ case earlyBird
+ case regular
+ case lastMinute
+
+ var multiplier: Double {
+ switch self {
+ case .earlyBird: return 0.7 // 30% off
+ case .regular: return 1.0 // Full price
+ case .lastMinute: return 1.2 // 20% markup
+ }
+ }
+ }
+
+ @Decides([
+ (DateComparisonSpec(
+ eventKey: "event_date",
+ comparison: .before,
+ date: Date().addingTimeInterval(-30 * 86400) // 30 days before
+ ), PricingTier.earlyBird),
+ (DateComparisonSpec(
+ eventKey: "event_date",
+ comparison: .before,
+ date: Date().addingTimeInterval(-3 * 86400) // 3 days before
+ ), PricingTier.regular)
+ ], or: .lastMinute)
+ var pricingTier: PricingTier
+
+ func getPrice(basePrice: Double) -> Double {
+ return basePrice * pricingTier.multiplier
+ }
+}
+```
+
+### API Rate Limit Selector
+
+```swift
+class APIRateLimitManager {
+ struct RateLimit {
+ let requestsPerMinute: Int
+ let burstSize: Int
+
+ static let free = RateLimit(requestsPerMinute: 10, burstSize: 2)
+ static let basic = RateLimit(requestsPerMinute: 60, burstSize: 10)
+ static let pro = RateLimit(requestsPerMinute: 600, burstSize: 50)
+ static let enterprise = RateLimit(requestsPerMinute: 6000, burstSize: 500)
+ }
+
+ @Decides([
+ (SubscriptionStatusSpec(status: .enterprise), RateLimit.enterprise),
+ (SubscriptionStatusSpec(status: .professional), RateLimit.pro),
+ (SubscriptionStatusSpec(status: .basic), RateLimit.basic)
+ ], or: .free)
+ var currentLimit: RateLimit
+
+ func canMakeRequest() -> Bool {
+ let provider = DefaultContextProvider.shared
+ let requestsThisMinute = provider.currentContext()
+ .counter(for: "requests_this_minute")
+
+ return requestsThisMinute < currentLimit.requestsPerMinute
+ }
+
+ func canBurst(requestCount: Int) -> Bool {
+ return requestCount <= currentLimit.burstSize
+ }
+}
+```
+
+### Theme Selection System
+
+```swift
+struct ThemeManager {
+ enum Theme: String {
+ case dark = "dark"
+ case light = "light"
+ case auto = "auto"
+ case highContrast = "high_contrast"
+
+ var colors: ColorScheme {
+ // Return appropriate color scheme
+ switch self {
+ case .dark: return .darkColors
+ case .light: return .lightColors
+ case .auto: return .systemColors
+ case .highContrast: return .highContrastColors
+ }
+ }
+ }
+
+ @Decides(decide: { context in
+ // User preference takes priority
+ if let userTheme = context.userData["theme_preference"] as? String,
+ let theme = Theme(rawValue: userTheme) {
+ return theme
+ }
+
+ // Accessibility setting
+ if context.flag(for: "high_contrast_mode") {
+ return .highContrast
+ }
+
+ // Time-based auto theme
+ let hour = Calendar.current.component(.hour, from: context.currentDate)
+ if hour >= 18 || hour < 6 {
+ return .dark
+ } else {
+ return .light
+ }
+ }, or: .auto)
+ var currentTheme: Theme
+
+ func applyTheme() {
+ UIApplication.shared.updateAppearance(currentTheme.colors)
+ }
+}
+```
+
+### Notification Priority Router
+
+```swift
+class NotificationRouter {
+ enum Priority: Int {
+ case critical = 4
+ case high = 3
+ case medium = 2
+ case low = 1
+
+ var deliveryChannel: [DeliveryChannel] {
+ switch self {
+ case .critical:
+ return [.push, .sms, .email, .inApp]
+ case .high:
+ return [.push, .email, .inApp]
+ case .medium:
+ return [.push, .inApp]
+ case .low:
+ return [.inApp]
+ }
+ }
+
+ var retryAttempts: Int {
+ switch self {
+ case .critical: return 5
+ case .high: return 3
+ case .medium: return 2
+ case .low: return 1
+ }
+ }
+ }
+
+ @Decides(decide: { context in
+ let notificationType = context.userData["notification_type"] as? String ?? ""
+
+ switch notificationType {
+ case "security_alert":
+ return Priority.critical
+ case "payment_required":
+ return Priority.high
+ case "feature_update":
+ return Priority.medium
+ case "newsletter":
+ return Priority.low
+ default:
+ return nil // Use fallback
+ }
+ }, or: .low)
+ var notificationPriority: Priority
+
+ func send(notification: Notification) {
+ let channels = notificationPriority.deliveryChannel
+ let retries = notificationPriority.retryAttempts
+
+ deliver(notification, via: channels, retries: retries)
+ }
+}
+```
+
+## Builder Pattern Usage
+
+Create complex decision logic with the builder API:
+
+```swift
+// Build specification inline
+@Decides(build: { builder in
+ builder
+ .add(VIPUserSpec(), result: "vip")
+ .add(PremiumUserSpec(), result: "premium")
+ .add(FreeUserSpec(), result: "free")
+}, or: "guest")
+var userCategory: String
+
+// Separate builder construction
+let contentBuilder = FirstMatchSpec.builder()
+contentBuilder
+ .add(HolidaySeasonSpec(), result: "holiday_theme")
+ .add(UserBirthdaySpec(), result: "birthday_theme")
+ .add(NewUserSpec(), result: "welcome_theme")
+
+@Decides(using: contentBuilder.fallback("default_theme").build(), or: "default_theme")
+var themeVariant: String
+```
+
+## Testing
+
+Test decision logic with ``MockContextProvider``:
+
+```swift
+func testTierSelection() {
+ let provider = MockContextProvider()
+ .withFlag("premium_subscription", value: true)
+
+ @Decides(
+ provider: provider,
+ firstMatch: [
+ (FeatureFlagSpec(flagKey: "enterprise_subscription"), "enterprise"),
+ (FeatureFlagSpec(flagKey: "premium_subscription"), "premium")
+ ],
+ fallback: "free"
+ )
+ var tier: String
+
+ XCTAssertEqual(tier, "premium")
+
+ // Test fallback
+ provider.setFlag("premium_subscription", to: false)
+ XCTAssertEqual(tier, "free")
+
+ // Test projected value
+ provider.setFlag("premium_subscription", to: true)
+ XCTAssertNotNil($tier)
+ XCTAssertEqual($tier, "premium")
+}
+
+func testProjectedValue() {
+ let provider = MockContextProvider()
+
+ @Decides(
+ provider: provider,
+ firstMatch: [
+ (FeatureFlagSpec(flagKey: "special_offer"), "special")
+ ],
+ fallback: "standard"
+ )
+ var offerType: String
+
+ // No specification matches - using fallback
+ XCTAssertEqual(offerType, "standard")
+ XCTAssertNil($offerType)
+
+ // Specification matches
+ provider.setFlag("special_offer", to: true)
+ XCTAssertEqual(offerType, "special")
+ XCTAssertEqual($offerType, "special")
+}
+```
+
+## Best Practices
+
+### Order Specifications by Priority
+
+```swift
+// ✅ Good - most specific first
+@Decides([
+ (VIPMemberSpec(), "vip"), // Most specific
+ (PremiumMemberSpec(), "premium"), // More specific
+ (RegisteredUserSpec(), "registered") // Least specific
+], or: "guest")
+var userLevel: String
+
+// ❌ Avoid - wrong order
+@Decides([
+ (RegisteredUserSpec(), "registered"), // Too broad, matches VIP/Premium too
+ (PremiumMemberSpec(), "premium"),
+ (VIPMemberSpec(), "vip")
+], or: "guest")
+var badUserLevel: String // VIP users will get "registered"!
+```
+
+### Use Type-Safe Result Types
+
+```swift
+// ✅ Good - enum for type safety
+enum AccessLevel {
+ case admin, moderator, user, guest
+}
+
+@Decides([
+ (AdminSpec(), AccessLevel.admin),
+ (ModeratorSpec(), AccessLevel.moderator),
+ (UserSpec(), AccessLevel.user)
+], or: .guest)
+var accessLevel: AccessLevel
+
+// ❌ Avoid - stringly-typed
+@Decides([
+ (AdminSpec(), "admin"),
+ (ModeratorSpec(), "moderator"),
+ (UserSpec(), "user")
+], or: "guest")
+var accessString: String // Typo-prone
+```
+
+### Provide Meaningful Fallbacks
+
+```swift
+// ✅ Good - sensible default
+@Decides([
+ (PremiumUserSpec(), 25.0),
+ (StandardUserSpec(), 10.0)
+], or: 0.0) // No discount for others
+var discount: Double
+
+// ✅ Good - safe fallback
+@Decides([
+ (HighSecuritySpec(), .twoFactor),
+ (MediumSecuritySpec(), .password)
+], or: .passwordWithEmail) // Reasonable security level
+var authMethod: AuthMethod
+
+// ❌ Avoid - unsafe fallback
+@Decides([
+ (AdminSpec(), .fullAccess),
+ (UserSpec(), .limitedAccess)
+], or: .fullAccess) // Too permissive!
+var access: AccessLevel
+```
+
+### Use Projected Value for Analytics
+
+```swift
+@Decides([
+ (PromoCodeSpec(), "promo_price"),
+ (MembershipSpec(), "member_price")
+], or: "regular_price")
+var pricingStrategy: String
+
+func recordPurchase() {
+ if let strategyUsed = $pricingStrategy {
+ analytics.track("purchase_with_strategy", ["strategy": strategyUsed])
+ } else {
+ analytics.track("purchase_regular_price")
+ }
+}
+```
+
+## Performance Considerations
+
+- **First-Match Evaluation**: Stops at first satisfied specification; order matters for performance
+- **Specification Order**: Place most likely matches first for better performance
+- **Fallback Overhead**: Minimal; fallback value is only used when needed
+- **Context Fetching**: Context retrieved once per property access
+- **No Caching**: Re-evaluates on each access; consider caching for expensive operations
+- **Builder Overhead**: Builder pattern has slight overhead; use direct initialization for simple cases
+
+## Topics
+
+### Creating Property Wrappers
+
+- ``init(provider:using:fallback:)``
+- ``init(provider:firstMatch:fallback:)``
+- ``init(provider:decide:fallback:)``
+
+### Property Values
+
+- ``wrappedValue``
+- ``projectedValue``
+
+## See Also
+
+-
+-
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/DecisionSpec.md b/Sources/SpecificationCore/Documentation.docc/DecisionSpec.md
new file mode 100644
index 0000000..36394ac
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/DecisionSpec.md
@@ -0,0 +1,381 @@
+# ``SpecificationCore/DecisionSpec``
+
+A protocol for specifications that return typed results beyond boolean values.
+
+## Overview
+
+The `DecisionSpec` protocol extends the Specification Pattern to support decision-making with typed payloads. While regular ``Specification`` protocols return boolean values, `DecisionSpec` allows you to return rich, typed results when a specification is satisfied.
+
+### Key Benefits
+
+- **Typed Results**: Return specific values (strings, enums, objects) instead of just `true`/`false`
+- **Priority-Based Decisions**: Evaluate multiple specifications and return the first matching result
+- **Type Safety**: Generic associated types ensure compile-time correctness
+- **Flexibility**: Bridge boolean specifications to decision specs easily
+- **Composability**: Works alongside regular specifications
+
+### When to Use DecisionSpec
+
+Use `DecisionSpec` when you need to:
+- Make priority-based decisions with typed outcomes
+- Map business rules to specific actions or values
+- Implement feature flags that return configuration objects
+- Create eligibility systems that provide reasons or results
+- Build routing or dispatching logic based on conditions
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+struct User {
+ let subscriptionTier: String
+ let accountAge: Int
+}
+
+// Define a decision specification
+struct DiscountDecisionSpec: DecisionSpec {
+ func decide(_ user: User) -> String? {
+ if user.subscriptionTier == "premium" {
+ return "PREMIUM20"
+ }
+ if user.accountAge > 365 {
+ return "LOYAL15"
+ }
+ return nil
+ }
+}
+
+// Use the decision spec
+let spec = DiscountDecisionSpec()
+let user = User(subscriptionTier: "premium", accountAge: 200)
+
+if let discountCode = spec.decide(user) {
+ print("Apply discount: \(discountCode)") // "PREMIUM20"
+}
+```
+
+## Bridging Boolean Specifications
+
+Convert any ``Specification`` to a ``DecisionSpec`` using the `returning(_:)` method:
+
+```swift
+struct PremiumUserSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.subscriptionTier == "premium"
+ }
+}
+
+// Convert to DecisionSpec
+let premiumDiscount = PremiumUserSpec().returning("PREMIUM20")
+
+if let code = premiumDiscount.decide(user) {
+ print("Discount code: \(code)")
+}
+```
+
+## Priority-Based Decisions
+
+Use ``FirstMatchSpec`` to evaluate multiple decision specs in priority order:
+
+```swift
+struct LoyaltyDecisionSpec: DecisionSpec {
+ func decide(_ user: User) -> String? {
+ user.accountAge > 365 ? "LOYAL15" : nil
+ }
+}
+
+struct NewUserDecisionSpec: DecisionSpec {
+ func decide(_ user: User) -> String? {
+ user.accountAge < 30 ? "WELCOME10" : nil
+ }
+}
+
+// Evaluate in order: premium → loyalty → new user → default
+let discountSpec = FirstMatchSpec(
+ specs: [
+ DiscountDecisionSpec(),
+ LoyaltyDecisionSpec(),
+ NewUserDecisionSpec()
+ ],
+ defaultResult: "STANDARD5"
+)
+
+let discount = discountSpec.decide(user) // Returns first match or default
+```
+
+## Type-Erased Decision Specs
+
+Use ``AnyDecisionSpec`` to store decision specs of the same context and result types:
+
+```swift
+// Store different decision specs in an array
+let rules: [AnyDecisionSpec] = [
+ AnyDecisionSpec(DiscountDecisionSpec()),
+ AnyDecisionSpec(LoyaltyDecisionSpec()),
+ AnyDecisionSpec { user in
+ user.subscriptionTier == "trial" ? "TRIAL5" : nil
+ }
+]
+
+// Evaluate all rules
+for rule in rules {
+ if let result = rule.decide(user) {
+ print("Matched rule with result: \(result)")
+ break
+ }
+}
+```
+
+## Creating Decision Specs from Predicates
+
+Use ``PredicateDecisionSpec`` to create decision specs from simple predicates:
+
+```swift
+let seniorDiscount = PredicateDecisionSpec(
+ predicate: { (user: User) in user.accountAge > 1000 },
+ result: "SENIOR25"
+)
+
+if let code = seniorDiscount.decide(user) {
+ print("Senior discount: \(code)")
+}
+```
+
+## Using with Property Wrappers
+
+Combine decision specs with the ``Decides`` property wrapper:
+
+```swift
+struct DiscountViewModel {
+ let user: User
+
+ @Decides([
+ (PremiumUserSpec(), "PREMIUM20"),
+ (LoyaltyUserSpec(), "LOYAL15"),
+ (NewUserSpec(), "WELCOME10")
+ ], or: "STANDARD5")
+ var discountCode: String
+
+ init(user: User) {
+ self.user = user
+ _discountCode = Decides(
+ [
+ (PremiumUserSpec(), "PREMIUM20"),
+ (LoyaltyUserSpec(), "LOYAL15"),
+ (NewUserSpec(), "WELCOME10")
+ ],
+ or: "STANDARD5",
+ with: user
+ )
+ }
+}
+
+let viewModel = DiscountViewModel(user: user)
+print("Discount: \(viewModel.discountCode)") // Always has a value
+```
+
+## Optional Results with Maybe
+
+For decisions that might not have a result, use ``Maybe``:
+
+```swift
+struct BonusViewModel {
+ let user: User
+
+ @Maybe([
+ (PremiumUserSpec(), "Free shipping"),
+ (LoyaltyUserSpec(), "Bonus points")
+ ])
+ var bonus: String?
+
+ init(user: User) {
+ self.user = user
+ _bonus = Maybe(
+ [
+ (PremiumUserSpec(), "Free shipping"),
+ (LoyaltyUserSpec(), "Bonus points")
+ ],
+ with: user
+ )
+ }
+}
+
+let viewModel = BonusViewModel(user: user)
+if let bonus = viewModel.bonus {
+ print("Bonus: \(bonus)")
+}
+```
+
+## Advanced Patterns
+
+### Enum-Based Results
+
+Return enums for type-safe, exhaustive results:
+
+```swift
+enum AccessLevel {
+ case admin
+ case moderator
+ case user
+ case guest
+}
+
+struct AccessLevelDecisionSpec: DecisionSpec {
+ func decide(_ user: User) -> AccessLevel? {
+ switch user.subscriptionTier {
+ case "admin": return .admin
+ case "premium": return .moderator
+ case "basic": return .user
+ default: return .guest
+ }
+ }
+}
+```
+
+### Structured Result Types
+
+Return complex objects with metadata:
+
+```swift
+struct PricingDecision {
+ let basePrice: Decimal
+ let discountPercent: Double
+ let discountReason: String
+}
+
+struct PricingDecisionSpec: DecisionSpec {
+ func decide(_ user: User) -> PricingDecision? {
+ if user.subscriptionTier == "premium" {
+ return PricingDecision(
+ basePrice: 99.99,
+ discountPercent: 20,
+ discountReason: "Premium subscriber"
+ )
+ }
+ return nil
+ }
+}
+```
+
+### Combining with Context Providers
+
+Use with ``EvaluationContext`` for dynamic decisions:
+
+```swift
+struct FeatureConfigDecisionSpec: DecisionSpec {
+ func decide(_ context: EvaluationContext) -> FeatureConfig? {
+ let isPremium = context.flag(for: "is_premium") == true
+ let isEarlyAccess = context.flag(for: "early_access") == true
+
+ if isPremium && isEarlyAccess {
+ return FeatureConfig(tier: .premium, features: ["ai", "analytics", "priority"])
+ } else if isPremium {
+ return FeatureConfig(tier: .premium, features: ["ai", "analytics"])
+ }
+ return nil
+ }
+}
+```
+
+## Best Practices
+
+### Return nil for Non-Matches
+
+Always return `nil` when the decision spec doesn't match:
+
+```swift
+// ✅ Good
+func decide(_ user: User) -> String? {
+ guard user.subscriptionTier == "premium" else {
+ return nil // Explicit non-match
+ }
+ return "PREMIUM20"
+}
+
+// ❌ Avoid - throwing errors or returning empty values
+func decide(_ user: User) -> String? {
+ if user.subscriptionTier != "premium" {
+ return "" // Ambiguous - is this a match or not?
+ }
+ return "PREMIUM20"
+}
+```
+
+### Use FirstMatchSpec for Priority Lists
+
+When you have multiple decision specs, use ``FirstMatchSpec`` for clear priority ordering:
+
+```swift
+// ✅ Good - explicit priorities
+let spec = FirstMatchSpec(
+ specs: [highPrioritySpec, mediumPrioritySpec, lowPrioritySpec],
+ defaultResult: defaultValue
+)
+
+// ❌ Avoid - complex nested conditionals
+func decide(_ context: Context) -> Result? {
+ if let high = highPrioritySpec.decide(context) { return high }
+ if let medium = mediumPrioritySpec.decide(context) { return medium }
+ if let low = lowPrioritySpec.decide(context) { return low }
+ return defaultValue
+}
+```
+
+### Provide Meaningful Results
+
+Return values that are useful to callers:
+
+```swift
+// ✅ Good - informative results
+enum RecommendationType {
+ case upgrade(tier: String, savings: Decimal)
+ case renew(discount: Double)
+ case downgrade(reason: String)
+}
+
+// ❌ Avoid - opaque results
+typealias Result = Int // What does the number mean?
+```
+
+## Performance Considerations
+
+- **Lazy Evaluation**: Decision specs only execute when `decide(_:)` is called
+- **Short-Circuit Logic**: ``FirstMatchSpec`` stops after the first match
+- **Result Caching**: Consider caching expensive decision results when appropriate
+- **Nil Returns**: Returning `nil` is cheap - use it for non-matches
+
+## Topics
+
+### Essential Protocol
+
+- ``decide(_:)``
+
+### Bridging from Specifications
+
+- ``Specification/returning(_:)``
+- ``BooleanDecisionAdapter``
+
+### Type Erasure
+
+- ``AnyDecisionSpec``
+
+### Predicate-Based Decisions
+
+- ``PredicateDecisionSpec``
+
+### Priority-Based Decisions
+
+- ``FirstMatchSpec``
+
+### Property Wrappers
+
+- ``Decides``
+- ``Maybe``
+
+## See Also
+
+-
+-
+- ``Decides``
+- ``Maybe``
diff --git a/Sources/SpecificationCore/Documentation.docc/DefaultContextProvider.md b/Sources/SpecificationCore/Documentation.docc/DefaultContextProvider.md
new file mode 100644
index 0000000..f09eeda
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/DefaultContextProvider.md
@@ -0,0 +1,699 @@
+# ``SpecificationCore/DefaultContextProvider``
+
+A thread-safe context provider that maintains application-wide state for specification evaluation.
+
+## Overview
+
+`DefaultContextProvider` is the primary context provider in SpecificationCore, designed to manage counters, feature flags, events, and user data that specifications use for evaluation. It provides a shared singleton instance and supports reactive updates through Combine publishers.
+
+### Key Features
+
+- **Thread-Safe**: All operations protected by locks for concurrent access
+- **Reactive Updates**: Publishes changes via Combine when state mutates
+- **Flexible Storage**: Supports counters, flags, events, and arbitrary user data
+- **Singleton Pattern**: Provides a shared instance for application-wide state
+- **Async Support**: Both sync and async context access methods
+
+### When to Use DefaultContextProvider
+
+Use `DefaultContextProvider` when you need to:
+- Maintain application-wide specification context
+- Track counters, events, and feature flags
+- Provide dynamic context to specifications at runtime
+- Enable reactive specification evaluation in SwiftUI
+- Share context state across your application
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+// Use the shared instance
+let provider = DefaultContextProvider.shared
+
+// Configure state
+provider.setFlag("premium_features", to: true)
+provider.setCounter("api_calls", to: 50)
+provider.recordEvent("last_login")
+
+// Get context for specifications
+let context = provider.currentContext()
+
+// Use with specifications
+@Satisfies(using: FeatureFlagSpec(flagKey: "premium_features"))
+var showPremiumFeatures: Bool
+```
+
+## Shared Singleton
+
+Access the application-wide shared instance:
+
+```swift
+// Shared instance available throughout the app
+let provider = DefaultContextProvider.shared
+
+// Configure once, use everywhere
+provider.setFlag("dark_mode", to: true)
+provider.setCounter("app_launches", to: 1)
+
+// All specifications use the same shared state
+@Satisfies(using: FeatureFlagSpec(flagKey: "dark_mode"))
+var useDarkMode: Bool // Reads from shared instance
+```
+
+## Custom Instances
+
+Create isolated instances for testing or module-specific state:
+
+```swift
+// Create a separate instance
+let testProvider = DefaultContextProvider()
+testProvider.setFlag("test_mode", to: true)
+
+// Use in specific contexts
+class FeatureService {
+ let contextProvider: DefaultContextProvider
+
+ init(contextProvider: DefaultContextProvider = .shared) {
+ self.contextProvider = contextProvider
+ }
+
+ func checkFeature() -> Bool {
+ let context = contextProvider.currentContext()
+ return context.flag(for: "feature_enabled")
+ }
+}
+
+// Production uses shared
+let prodService = FeatureService()
+
+// Tests use isolated instance
+let testService = FeatureService(contextProvider: testProvider)
+```
+
+## Counter Management
+
+Track and manipulate integer counters:
+
+### Setting Counters
+
+```swift
+let provider = DefaultContextProvider.shared
+
+// Set counter to specific value
+provider.setCounter("login_attempts", to: 3)
+provider.setCounter("api_calls_today", to: 100)
+provider.setCounter("items_viewed", to: 0)
+```
+
+### Incrementing Counters
+
+```swift
+// Increment by 1 (default)
+provider.incrementCounter("page_views")
+
+// Increment by specific amount
+provider.incrementCounter("api_calls", by: 10)
+
+// Get the new value
+let newCount = provider.incrementCounter("clicks", by: 1)
+print("New click count: \(newCount)")
+```
+
+### Decrementing Counters
+
+```swift
+// Decrement by 1 (default)
+provider.decrementCounter("remaining_tries")
+
+// Decrement by specific amount
+provider.decrementCounter("credits", by: 5)
+
+// Counters never go below zero
+provider.setCounter("balance", to: 3)
+provider.decrementCounter("balance", by: 10) // Result: 0, not -7
+```
+
+### Reading and Resetting
+
+```swift
+// Read current value
+let currentCount = provider.getCounter("attempts") // Returns 0 if not found
+
+// Reset to zero
+provider.resetCounter("daily_actions")
+
+// Clear all counters
+provider.clearCounters()
+```
+
+### Using with Specifications
+
+```swift
+// Track API call limits
+provider.setCounter("api_calls", to: 50)
+
+@Satisfies(using: MaxCountSpec(counterKey: "api_calls", maximumCount: 100))
+var canMakeAPICall: Bool
+
+if canMakeAPICall {
+ makeAPICall()
+ provider.incrementCounter("api_calls")
+}
+```
+
+## Feature Flag Management
+
+Manage boolean feature toggles:
+
+### Setting Flags
+
+```swift
+let provider = DefaultContextProvider.shared
+
+// Enable/disable features
+provider.setFlag("dark_mode", to: true)
+provider.setFlag("experimental_ui", to: false)
+provider.setFlag("analytics_enabled", to: true)
+```
+
+### Toggling Flags
+
+```swift
+// Toggle between true/false
+let newValue = provider.toggleFlag("debug_mode")
+print("Debug mode is now: \(newValue)")
+
+// Toggle returns the new value
+provider.setFlag("feature_a", to: false)
+provider.toggleFlag("feature_a") // Returns true
+```
+
+### Reading Flags
+
+```swift
+// Read current value (false if not found)
+let isDarkMode = provider.getFlag("dark_mode")
+
+// Clear all flags
+provider.clearFlags()
+```
+
+### Using with Specifications
+
+```swift
+// Configure feature flags
+provider.setFlag("premium_features", to: true)
+
+@Satisfies(using: FeatureFlagSpec(flagKey: "premium_features"))
+var showPremiumUI: Bool
+
+if showPremiumUI {
+ // Render premium interface
+}
+```
+
+## Event Tracking
+
+Record and retrieve event timestamps:
+
+### Recording Events
+
+```swift
+let provider = DefaultContextProvider.shared
+
+// Record event with current timestamp
+provider.recordEvent("user_logged_in")
+provider.recordEvent("tutorial_completed")
+provider.recordEvent("notification_shown")
+
+// Record event with specific timestamp
+let customDate = Date().addingTimeInterval(-3600) // 1 hour ago
+provider.recordEvent("last_purchase", at: customDate)
+```
+
+### Reading Events
+
+```swift
+// Get event timestamp
+if let lastLogin = provider.getEvent("user_logged_in") {
+ print("Last login: \(lastLogin)")
+}
+
+// Remove an event
+provider.removeEvent("temporary_flag")
+
+// Clear all events
+provider.clearEvents()
+```
+
+### Using with Time-Based Specifications
+
+```swift
+// Record when notification was shown
+provider.recordEvent("last_notification")
+
+// Cooldown spec ensures minimum time between notifications
+@Satisfies(using: CooldownIntervalSpec(
+ eventKey: "last_notification",
+ interval: 3600 // 1 hour cooldown
+))
+var canShowNotification: Bool
+
+if canShowNotification {
+ showNotification()
+ provider.recordEvent("last_notification")
+}
+```
+
+## User Data Storage
+
+Store arbitrary typed data:
+
+### Setting User Data
+
+```swift
+let provider = DefaultContextProvider.shared
+
+// Store different types
+provider.setUserData("user_id", to: "abc123")
+provider.setUserData("subscription_tier", to: "premium")
+provider.setUserData("onboarding_completed", to: true)
+
+// Store custom objects
+struct UserProfile {
+ let name: String
+ let age: Int
+}
+
+let profile = UserProfile(name: "Alice", age: 30)
+provider.setUserData("user_profile", to: profile)
+```
+
+### Reading User Data
+
+```swift
+// Type-safe retrieval
+let userId = provider.getUserData("user_id", as: String.self)
+let tier = provider.getUserData("subscription_tier", as: String.self)
+let profile = provider.getUserData("user_profile", as: UserProfile.self)
+
+// Remove user data
+provider.removeUserData("temporary_data")
+
+// Clear all user data
+provider.clearUserData()
+```
+
+### Using in Specifications
+
+```swift
+provider.setUserData("subscription_tier", to: "premium")
+
+struct TierSpec: Specification {
+ func isSatisfiedBy(_ context: EvaluationContext) -> Bool {
+ let tier = context.userData(for: "subscription_tier", as: String.self)
+ return tier == "premium"
+ }
+}
+```
+
+## Custom Context Providers
+
+Register dynamic context providers:
+
+```swift
+let provider = DefaultContextProvider.shared
+
+// Register a provider for dynamic data
+provider.register(contextKey: "current_user_id") {
+ UserSession.current.userId
+}
+
+provider.register(contextKey: "is_online") {
+ NetworkMonitor.shared.isConnected
+}
+
+// Unregister when no longer needed
+provider.unregister(contextKey: "current_user_id")
+
+// Values are fetched fresh each time context is requested
+let context = provider.currentContext()
+let userId = context.userData(for: "current_user_id", as: String.self)
+```
+
+## Bulk Operations
+
+Manage all state at once:
+
+```swift
+let provider = DefaultContextProvider.shared
+
+// Clear everything
+provider.clearAll()
+
+// Clear specific categories
+provider.clearCounters()
+provider.clearFlags()
+provider.clearEvents()
+provider.clearUserData()
+```
+
+## Thread Safety
+
+All operations are thread-safe:
+
+```swift
+let provider = DefaultContextProvider.shared
+
+// Safe to call from any queue
+DispatchQueue.global().async {
+ provider.incrementCounter("background_task")
+}
+
+DispatchQueue.main.async {
+ provider.setFlag("ui_ready", to: true)
+}
+
+// Concurrent reads and writes are protected
+Task.detached {
+ provider.recordEvent("async_operation")
+}
+```
+
+## Reactive Updates with Combine
+
+Subscribe to context changes:
+
+```swift
+#if canImport(Combine)
+import Combine
+
+let provider = DefaultContextProvider.shared
+
+// Subscribe to all context updates
+let cancellable = provider.contextUpdates
+ .sink {
+ print("Context was updated")
+ // Refresh UI or re-evaluate specifications
+ }
+
+// Provider conforms to ContextUpdatesProviding
+// Updates are published whenever state changes
+provider.setFlag("feature", to: true) // Triggers update
+provider.incrementCounter("count") // Triggers update
+```
+
+## Async Context Stream
+
+Use async/await with context updates:
+
+```swift
+let provider = DefaultContextProvider.shared
+
+Task {
+ for await _ in provider.contextStream {
+ print("Context updated")
+ // Async handling of context changes
+ }
+}
+
+// Updates stream when state changes
+provider.recordEvent("user_action")
+```
+
+## Creating Specifications
+
+Build specifications using the provider:
+
+### Context-Aware Predicates
+
+```swift
+let provider = DefaultContextProvider.shared
+
+let spec = provider.contextualPredicate { context, user in
+ context.flag(for: "premium_enabled") &&
+ user.subscriptionTier == "premium"
+}
+
+// Use the specification
+let isEligible = spec.isSatisfiedBy(user)
+```
+
+### Dynamic Specifications
+
+```swift
+let provider = DefaultContextProvider.shared
+
+let dynamicSpec = provider.specification { context in
+ if context.flag(for: "use_new_rules") {
+ return AnySpecification(NewEligibilityRules())
+ } else {
+ return AnySpecification(LegacyEligibilityRules())
+ }
+}
+```
+
+## Testing with DefaultContextProvider
+
+Use separate instances for isolated testing:
+
+```swift
+class FeatureTests: XCTestCase {
+ var provider: DefaultContextProvider!
+
+ override func setUp() {
+ super.setUp()
+ provider = DefaultContextProvider() // Fresh instance
+ }
+
+ override func tearDown() {
+ provider.clearAll()
+ super.tearDown()
+ }
+
+ func testFeatureEligibility() {
+ // Configure test scenario
+ provider.setFlag("premium", to: true)
+ provider.setCounter("usage", to: 5)
+
+ let context = provider.currentContext()
+
+ // Test specification
+ XCTAssertTrue(eligibilitySpec.isSatisfiedBy(context))
+ }
+}
+```
+
+## Real-World Examples
+
+### API Rate Limiting
+
+```swift
+let provider = DefaultContextProvider.shared
+
+// Track API calls
+provider.setCounter("api_calls_today", to: 0)
+
+@Satisfies(using: MaxCountSpec(
+ counterKey: "api_calls_today",
+ maximumCount: 1000
+))
+var canMakeAPICall: Bool
+
+func makeAPIRequest() async throws -> Response {
+ guard canMakeAPICall else {
+ throw APIError.rateLimitExceeded
+ }
+
+ let response = try await performRequest()
+ provider.incrementCounter("api_calls_today")
+ return response
+}
+
+// Reset daily limit
+func resetDailyLimits() {
+ provider.resetCounter("api_calls_today")
+}
+```
+
+### Notification Cooldowns
+
+```swift
+let provider = DefaultContextProvider.shared
+
+@Satisfies(using: CooldownIntervalSpec(
+ eventKey: "last_notification",
+ interval: 3600 // 1 hour
+))
+var canShowNotification: Bool
+
+func showImportantNotification() {
+ guard canShowNotification else {
+ print("Too soon since last notification")
+ return
+ }
+
+ displayNotification()
+ provider.recordEvent("last_notification")
+}
+```
+
+### Feature Rollout
+
+```swift
+let provider = DefaultContextProvider.shared
+
+// Configure feature flags based on user segment
+func configureFeatureFlags(for user: User) {
+ if user.isBetaTester {
+ provider.setFlag("new_ui", to: true)
+ provider.setFlag("experimental_features", to: true)
+ } else {
+ provider.setFlag("new_ui", to: false)
+ provider.setFlag("experimental_features", to: false)
+ }
+}
+
+// Use throughout the app
+@Satisfies(using: FeatureFlagSpec(flagKey: "new_ui"))
+var useNewUI: Bool
+```
+
+## Best Practices
+
+### Use Shared Instance for Application State
+
+```swift
+// ✅ Good - shared state across app
+let provider = DefaultContextProvider.shared
+provider.setFlag("dark_mode", to: true)
+
+// ❌ Avoid - creating multiple instances fragments state
+let provider1 = DefaultContextProvider()
+let provider2 = DefaultContextProvider() // Different state!
+```
+
+### Inject Provider for Testability
+
+```swift
+// ✅ Good - dependency injection
+class FeatureService {
+ let provider: DefaultContextProvider
+
+ init(provider: DefaultContextProvider = .shared) {
+ self.provider = provider
+ }
+}
+
+// Easy to test
+let testService = FeatureService(provider: DefaultContextProvider())
+
+// ❌ Avoid - hard-coded dependency
+class FeatureService {
+ func check() {
+ let context = DefaultContextProvider.shared.currentContext() // Hard to test
+ }
+}
+```
+
+### Clear Test State
+
+```swift
+// ✅ Good - clean slate for each test
+override func setUp() {
+ provider = DefaultContextProvider()
+}
+
+override func tearDown() {
+ provider.clearAll()
+}
+
+// ❌ Avoid - state leaks between tests
+func testA() {
+ provider.setFlag("test", to: true) // Not cleared
+}
+
+func testB() {
+ // Might fail if testA ran first
+}
+```
+
+## Performance Considerations
+
+- **Thread Safety Overhead**: Locks add minimal overhead; optimized for concurrent access
+- **Reactive Updates**: Combine publishers add memory overhead; only subscribe when needed
+- **Context Creation**: `currentContext()` creates a new struct each time; cheap operation
+- **Dictionary Storage**: O(1) lookups but with dictionary overhead
+- **Bulk Clears**: More efficient than removing items one by one
+
+## Topics
+
+### Shared Instance
+
+- ``shared``
+
+### Creating Providers
+
+- ``init(launchDate:)``
+
+### Counter Management
+
+- ``setCounter(_:to:)``
+- ``incrementCounter(_:by:)``
+- ``decrementCounter(_:by:)``
+- ``getCounter(_:)``
+- ``resetCounter(_:)``
+
+### Flag Management
+
+- ``setFlag(_:to:)``
+- ``toggleFlag(_:)``
+- ``getFlag(_:)``
+
+### Event Management
+
+- ``recordEvent(_:)``
+- ``recordEvent(_:at:)``
+- ``getEvent(_:)``
+- ``removeEvent(_:)``
+
+### User Data Management
+
+- ``setUserData(_:to:)``
+- ``getUserData(_:as:)``
+- ``removeUserData(_:)``
+
+### Bulk Operations
+
+- ``clearAll()``
+- ``clearCounters()``
+- ``clearFlags()``
+- ``clearEvents()``
+- ``clearUserData()``
+
+### Context Registration
+
+- ``register(contextKey:provider:)``
+- ``unregister(contextKey:)``
+
+### Creating Specifications
+
+- ``specification(_:)``
+- ``contextualPredicate(_:)``
+
+### Context Provider Protocol
+
+- ``currentContext()``
+
+### Reactive Updates
+
+- ``objectWillChange``
+- ``contextUpdates``
+- ``contextStream``
+
+## See Also
+
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/EvaluationContext.md b/Sources/SpecificationCore/Documentation.docc/EvaluationContext.md
new file mode 100644
index 0000000..591af39
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/EvaluationContext.md
@@ -0,0 +1,469 @@
+# ``SpecificationCore/EvaluationContext``
+
+A context object that holds data needed for specification evaluation.
+
+## Overview
+
+`EvaluationContext` is a value type that serves as a container for all the information specifications might need to make their decisions. It provides structured storage for timestamps, counters, feature flags, events, user data, and segments.
+
+### Key Benefits
+
+- **Structured Data**: Organized storage for different types of runtime data
+- **Value Semantics**: Immutable struct with copy-on-write behavior
+- **Type Safety**: Strongly-typed access methods with safe defaults
+- **Builder Pattern**: Convenient methods for creating modified copies
+- **Platform Independent**: Works across all Swift platforms
+
+### When to Use EvaluationContext
+
+Use `EvaluationContext` when you need to:
+- Provide runtime data to specifications
+- Track counters, flags, and events for business logic
+- Pass contextual information through specification evaluation
+- Test specifications with controlled context scenarios
+- Store user segments and feature toggles
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+// Create a context
+let context = EvaluationContext(
+ currentDate: Date(),
+ flags: ["premium_features": true],
+ counters: ["api_calls": 50],
+ events: ["last_login": Date()]
+)
+
+// Access data
+let hasPremium = context.flag(for: "premium_features") // true
+let callCount = context.counter(for: "api_calls") // 50
+let lastLogin = context.event(for: "last_login") // Date?
+
+// Use with specifications
+struct FeatureFlagSpec: Specification {
+ let flagKey: String
+
+ func isSatisfiedBy(_ context: EvaluationContext) -> Bool {
+ context.flag(for: flagKey)
+ }
+}
+
+let spec = FeatureFlagSpec(flagKey: "premium_features")
+spec.isSatisfiedBy(context) // true
+```
+
+## Context Properties
+
+### Timestamps
+
+```swift
+// Current date for time-based evaluations
+let context = EvaluationContext(
+ currentDate: Date(),
+ launchDate: Date().addingTimeInterval(-3600) // 1 hour ago
+)
+
+// Access timestamps
+let now = context.currentDate
+let launch = context.launchDate
+let runtime = context.timeSinceLaunch // 3600 seconds
+```
+
+###Counters
+
+Store and retrieve integer counters:
+
+```swift
+let context = EvaluationContext(
+ counters: [
+ "login_attempts": 3,
+ "api_calls_today": 150,
+ "items_in_cart": 5
+ ]
+)
+
+// Safe access with default value
+let attempts = context.counter(for: "login_attempts") // 3
+let missing = context.counter(for: "nonexistent") // 0 (default)
+
+// Use with MaxCountSpec
+let spec = MaxCountSpec(counterKey: "login_attempts", maximumCount: 5)
+spec.isSatisfiedBy(context) // true (3 < 5)
+```
+
+### Feature Flags
+
+Store and retrieve boolean feature toggles:
+
+```swift
+let context = EvaluationContext(
+ flags: [
+ "dark_mode": true,
+ "beta_features": false,
+ "analytics_enabled": true
+ ]
+)
+
+// Safe access with false default
+let darkMode = context.flag(for: "dark_mode") // true
+let missing = context.flag(for: "nonexistent") // false (default)
+
+// Use with feature flag specs
+if context.flag(for: "beta_features") {
+ // Show beta UI
+}
+```
+
+### Events
+
+Store and retrieve event timestamps:
+
+```swift
+let lastNotification = Date().addingTimeInterval(-7200) // 2 hours ago
+
+let context = EvaluationContext(
+ events: [
+ "last_notification": lastNotification,
+ "last_purchase": Date().addingTimeInterval(-86400), // 1 day ago
+ "registration_date": Date().addingTimeInterval(-604800) // 1 week ago
+ ]
+)
+
+// Access events
+let eventDate = context.event(for: "last_notification") // Date?
+
+// Calculate time since event
+if let timeSince = context.timeSinceEvent("last_notification") {
+ print("Last notification was \(timeSince) seconds ago") // 7200
+}
+
+// Use with time-based specs
+let cooldown = CooldownIntervalSpec(
+ eventKey: "last_notification",
+ interval: 3600 // 1 hour cooldown
+)
+cooldown.isSatisfiedBy(context) // true (7200 > 3600)
+```
+
+### User Data
+
+Store arbitrary typed data:
+
+```swift
+struct UserProfile {
+ let tier: String
+ let verified: Bool
+}
+
+let profile = UserProfile(tier: "premium", verified: true)
+
+let context = EvaluationContext(
+ userData: [
+ "user_profile": profile,
+ "user_id": "123456",
+ "subscription_end": Date().addingTimeInterval(2592000) // 30 days
+ ]
+)
+
+// Type-safe access
+let userProfile = context.userData(for: "user_profile", as: UserProfile.self)
+let userId = context.userData(for: "user_id", as: String.self)
+let endDate = context.userData(for: "subscription_end", as: Date.self)
+
+// Use in custom specifications
+struct ProfileSpec: Specification {
+ func isSatisfiedBy(_ context: EvaluationContext) -> Bool {
+ guard let profile = context.userData(for: "user_profile", as: UserProfile.self) else {
+ return false
+ }
+ return profile.tier == "premium" && profile.verified
+ }
+}
+```
+
+### Segments
+
+Store user segments as a set:
+
+```swift
+let context = EvaluationContext(
+ segments: ["vip", "beta_tester", "early_adopter"]
+)
+
+// Check segment membership
+let isVIP = context.segments.contains("vip") // true
+let isBeta = context.segments.contains("beta_tester") // true
+let isAdmin = context.segments.contains("admin") // false
+
+// Use with segment-based specs
+struct SegmentSpec: Specification {
+ let requiredSegment: String
+
+ func isSatisfiedBy(_ context: EvaluationContext) -> Bool {
+ context.segments.contains(requiredSegment)
+ }
+}
+```
+
+## Builder Pattern
+
+Create modified copies of contexts:
+
+```swift
+// Start with a base context
+let base = EvaluationContext(
+ flags: ["feature_a": true],
+ counters: ["count": 10]
+)
+
+// Create variations using builder methods
+let updated = base
+ .withFlags(["feature_a": true, "feature_b": true]) // Add more flags
+ .withCounters(["count": 11]) // Update counters
+ .withCurrentDate(Date()) // Update timestamp
+
+// Each method returns a new context (value semantics)
+print(base.counters["count"]) // 10 (unchanged)
+print(updated.counters["count"]) // 11 (modified)
+```
+
+### Individual Builder Methods
+
+```swift
+let context = EvaluationContext()
+
+// Build step by step
+let configured = context
+ .withFlags(["premium": true, "trial": false])
+ .withCounters(["logins": 5])
+ .withEvents(["last_action": Date()])
+ .withUserData(["user_id": "abc123"])
+ .withCurrentDate(Date())
+
+// All builder methods return new contexts
+```
+
+## Working with DefaultContextProvider
+
+`EvaluationContext` is typically created by ``DefaultContextProvider``:
+
+```swift
+let provider = DefaultContextProvider.shared
+
+// Configure provider state
+provider.setFlag("dark_mode", to: true)
+provider.setCounter("app_launches", to: 1)
+provider.recordEvent("first_launch")
+
+// Get context from provider
+let context = provider.currentContext()
+
+// Context contains all configured data
+let darkModeEnabled = context.flag(for: "dark_mode") // true
+let launches = context.counter(for: "app_launches") // 1
+let firstLaunch = context.event(for: "first_launch") // Date
+```
+
+## Testing with EvaluationContext
+
+Create test contexts with specific scenarios:
+
+```swift
+// Test counter limits
+let limitContext = EvaluationContext(
+ counters: ["attempts": 5]
+)
+
+let limitSpec = MaxCountSpec(counterKey: "attempts", maximumCount: 3)
+XCTAssertFalse(limitSpec.isSatisfiedBy(limitContext)) // 5 > 3
+
+// Test cooldown periods
+let cooldownContext = EvaluationContext(
+ currentDate: Date(),
+ events: ["last_action": Date().addingTimeInterval(-1800)] // 30 min ago
+)
+
+let cooldownSpec = CooldownIntervalSpec(
+ eventKey: "last_action",
+ interval: 3600 // 1 hour
+)
+XCTAssertFalse(cooldownSpec.isSatisfiedBy(cooldownContext)) // 1800 < 3600
+
+// Test feature flags
+let flagContext = EvaluationContext(
+ flags: ["new_ui": false]
+)
+
+let flagSpec = FeatureFlagSpec(flagKey: "new_ui")
+XCTAssertFalse(flagSpec.isSatisfiedBy(flagContext))
+```
+
+## Time-Based Evaluations
+
+Use context timestamps for time-dependent logic:
+
+```swift
+let context = EvaluationContext(
+ currentDate: Date(),
+ launchDate: Date().addingTimeInterval(-120) // 2 minutes ago
+)
+
+// Check runtime
+if context.timeSinceLaunch > 60 {
+ print("App running for more than 1 minute")
+}
+
+// Use calendar for date logic
+let calendar = context.calendar
+let hour = calendar.component(.hour, from: context.currentDate)
+
+if hour >= 22 || hour < 6 {
+ print("Night time")
+}
+
+// Time zone awareness
+let timeZone = context.timeZone
+print("Current timezone: \(timeZone.identifier)")
+```
+
+## Combining Context Data
+
+Combine different context types in specifications:
+
+```swift
+struct ComplexEligibilitySpec: Specification {
+ func isSatisfiedBy(_ context: EvaluationContext) -> Bool {
+ // Check multiple context aspects
+ let hasPremium = context.flag(for: "premium_user")
+ let withinLimit = context.counter(for: "api_calls") < 1000
+
+ guard let lastUse = context.event(for: "last_api_call"),
+ let timeSince = context.timeSinceEvent("last_api_call") else {
+ return false
+ }
+
+ let notOnCooldown = timeSince > 60 // 1 minute
+
+ return hasPremium && withinLimit && notOnCooldown
+ }
+}
+```
+
+## Best Practices
+
+### Use Appropriate Storage Types
+
+```swift
+// ✅ Good - use the right storage type
+let context = EvaluationContext(
+ flags: ["is_enabled": true], // Boolean → flags
+ counters: ["count": 42], // Integer → counters
+ events: ["timestamp": Date()], // Date → events
+ userData: ["object": customData] // Other types → userData
+)
+
+// ❌ Avoid - misusing storage types
+let bad = EvaluationContext(
+ userData: [
+ "is_enabled": true, // Should be a flag
+ "count": 42 // Should be a counter
+ ]
+)
+```
+
+### Provide Sensible Defaults
+
+```swift
+// ✅ Good - handle missing data gracefully
+let count = context.counter(for: "attempts") // Returns 0 if missing
+let hasFlag = context.flag(for: "feature") // Returns false if missing
+
+// ❌ Avoid - assuming data exists
+let userData = context.userData["key"]! // Crashes if missing
+```
+
+### Use Builder Pattern for Test Contexts
+
+```swift
+// ✅ Good - clear test setup
+func testPremiumFeatures() {
+ let context = EvaluationContext()
+ .withFlags(["premium": true])
+ .withCounters(["usage": 5])
+
+ XCTAssertTrue(premiumSpec.isSatisfiedBy(context))
+}
+
+// ❌ Verbose - manual construction
+func testPremiumFeatures() {
+ let context = EvaluationContext(
+ currentDate: Date(),
+ launchDate: Date(),
+ userData: [:],
+ counters: ["usage": 5],
+ events: [:],
+ flags: ["premium": true],
+ segments: []
+ )
+}
+```
+
+## Performance Considerations
+
+- **Value Semantics**: Context is a struct; copying is efficient via copy-on-write
+- **Immutability**: Contexts are immutable; modifications create new instances
+- **Safe Defaults**: Missing data returns safe defaults (0, false, nil) without overhead
+- **Dictionary Lookups**: Data access is O(1) but incurs dictionary overhead
+- **Builder Methods**: Each builder method creates a new context; chain wisely
+
+## Topics
+
+### Creating Contexts
+
+- ``init(currentDate:launchDate:userData:counters:events:flags:segments:)``
+
+### Properties
+
+- ``currentDate``
+- ``launchDate``
+- ``userData``
+- ``counters``
+- ``events``
+- ``flags``
+- ``segments``
+
+### Convenience Properties
+
+- ``timeSinceLaunch``
+- ``calendar``
+- ``timeZone``
+
+### Data Access
+
+- ``counter(for:)``
+- ``event(for:)``
+- ``flag(for:)``
+- ``userData(for:as:)``
+- ``timeSinceEvent(_:)``
+
+### Builder Methods
+
+- ``withUserData(_:)``
+- ``withCounters(_:)``
+- ``withEvents(_:)``
+- ``withFlags(_:)``
+- ``withCurrentDate(_:)``
+
+### Related Types
+
+- ``DefaultContextProvider``
+- ``MockContextProvider``
+- ``ContextProviding``
+
+## See Also
+
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/FirstMatchSpec.md b/Sources/SpecificationCore/Documentation.docc/FirstMatchSpec.md
new file mode 100644
index 0000000..121360c
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/FirstMatchSpec.md
@@ -0,0 +1,492 @@
+# ``SpecificationCore/FirstMatchSpec``
+
+A decision specification that evaluates specifications in priority order and returns the result of the first match.
+
+## Overview
+
+`FirstMatchSpec` implements a priority-based decision system where specifications are evaluated in order until one is satisfied. This is essential for tiered business rules, routing decisions, discount calculations, and any scenario requiring selection from a prioritized list of options.
+
+### Key Benefits
+
+- **Priority-Based**: Evaluates specifications in defined order
+- **First Match Wins**: Returns immediately upon first satisfaction
+- **Type-Safe Results**: Generic result type ensures compile-time correctness
+- **Builder Pattern**: Fluent interface for constructing decision chains
+- **Metadata Support**: Optional tracking of which rule matched
+
+### When to Use FirstMatchSpec
+
+Use `FirstMatchSpec` when you need to:
+- Implement tiered pricing or discount systems
+- Route users to different experiences based on criteria
+- Select the first applicable rule from multiple options
+- Make priority-based decisions with fallback values
+- Implement feature experiment assignments
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+struct User {
+ let tier: String
+ let daysSinceRegistration: Int
+ let isFirstPurchase: Bool
+}
+
+// Define discount tiers in priority order
+let discountSpec = FirstMatchSpec([
+ (PremiumMemberSpec(), 0.20), // 20% for premium
+ (LoyalCustomerSpec(), 0.15), // 15% for loyal
+ (FirstTimeBuyerSpec(), 0.10), // 10% for first-time
+ (RegularUserSpec(), 0.05) // 5% for everyone else
+])
+
+// Use with property wrapper
+@Decides(using: discountSpec, or: 0.0)
+var discountRate: Double
+
+print("Discount: \(discountRate)") // e.g., 0.20 for premium user
+```
+
+## Creating FirstMatchSpec
+
+### From Tuples
+
+```swift
+// Create with specification-result pairs
+let routingSpec = FirstMatchSpec([
+ (PremiumUserSpec(), "premium_dashboard"),
+ (BetaUserSpec(), "beta_dashboard"),
+ (NewUserSpec(), "onboarding_dashboard")
+])
+
+if let route = routingSpec.decide(user) {
+ navigateTo(route)
+}
+```
+
+### With Fallback
+
+```swift
+// Ensure a result is always returned
+let themeSpec = FirstMatchSpec.withFallback([
+ (DarkModePreferenceSpec(), "dark"),
+ (HighContrastSpec(), "high_contrast")
+], fallback: "light") // Default theme
+
+let theme = themeSpec.decide(context) // Never nil
+```
+
+### Using Builder Pattern
+
+```swift
+let contentSpec = FirstMatchSpec.builder()
+ .add(SubscriberSpec(), result: "premium_content")
+ .add(TrialUserSpec(), result: "trial_content")
+ .add(NewUserSpec(), result: "welcome_content")
+ .fallback("default_content")
+ .build()
+
+let content = contentSpec.decide(user) ?? "error"
+```
+
+## Priority-Based Decisions
+
+Specifications are evaluated in array order:
+
+```swift
+// High priority first, low priority last
+let supportTierSpec = FirstMatchSpec([
+ (EnterpriseCustomerSpec(), "priority_support"), // Checked first
+ (PremiumSubscriberSpec(), "premium_support"), // Checked second
+ (ActiveUserSpec(), "standard_support"), // Checked third
+ (RegisteredUserSpec(), "basic_support") // Checked last
+])
+
+// Returns first match
+let tier = supportTierSpec.decide(user)
+```
+
+## Using with Property Wrappers
+
+### Decides Wrapper
+
+For non-optional results with fallback:
+
+```swift
+struct PricingViewModel {
+ let user: User
+
+ @Decides([
+ (PremiumUserSpec(), 9.99),
+ (StudentUserSpec(), 4.99),
+ (TrialUserSpec(), 0.00)
+ ], or: 14.99) // Regular price
+ var monthlyPrice: Double
+
+ init(user: User) {
+ self.user = user
+ _monthlyPrice = Decides(
+ [
+ (PremiumUserSpec(), 9.99),
+ (StudentUserSpec(), 4.99),
+ (TrialUserSpec(), 0.00)
+ ],
+ or: 14.99,
+ with: user
+ )
+ }
+}
+```
+
+### Maybe Wrapper
+
+For optional results without fallback:
+
+```swift
+struct BonusViewModel {
+ let user: User
+
+ @Maybe([
+ (LoyaltyMemberSpec(), "loyalty_points"),
+ (ReferralUserSpec(), "referral_bonus")
+ ])
+ var availableBonus: String?
+
+ init(user: User) {
+ self.user = user
+ _availableBonus = Maybe(
+ [
+ (LoyaltyMemberSpec(), "loyalty_points"),
+ (ReferralUserSpec(), "referral_bonus")
+ ],
+ with: user
+ )
+ }
+}
+
+if let bonus = viewModel.availableBonus {
+ print("Bonus available: \(bonus)")
+}
+```
+
+## Builder Pattern
+
+Construct decision specs fluently:
+
+### Basic Building
+
+```swift
+let featureSpec = FirstMatchSpec.builder()
+ .add(FeatureFlagSpec(flagKey: "new_feature"), result: "new_ui")
+ .add(BetaTesterSpec(), result: "beta_ui")
+ .build()
+```
+
+### With Predicates
+
+```swift
+let experimentSpec = FirstMatchSpec.builder()
+ .add({ $0.tier == "enterprise" }, result: "variant_a")
+ .add({ $0.daysSinceRegistration < 30 }, result: "variant_b")
+ .add({ $0.age >= 65 }, result: "variant_c")
+ .fallback("control")
+ .build()
+```
+
+### With Metadata Tracking
+
+```swift
+let spec = FirstMatchSpec.builder()
+ .add(PremiumSpec(), result: "premium")
+ .add(TrialSpec(), result: "trial")
+ .withMetadata(true)
+ .build()
+
+if let (result, index) = spec.decideWithMetadata(user) {
+ print("Matched rule #\(index): \(result)")
+}
+```
+
+## Metadata and Debugging
+
+Track which specification matched:
+
+```swift
+let ruleSpec = FirstMatchSpec([
+ (Rule1Spec(), "action_1"),
+ (Rule2Spec(), "action_2"),
+ (Rule3Spec(), "action_3")
+], includeMetadata: true)
+
+// Get result with index
+if let (action, index) = ruleSpec.decideWithMetadata(user) {
+ print("Matched rule at index \(index): \(action)")
+ // Matched rule at index 1: action_2
+}
+```
+
+## Real-World Examples
+
+### Discount Calculation
+
+```swift
+struct Order {
+ let total: Decimal
+ let itemCount: Int
+ let customerTier: String
+}
+
+let discountSpec = FirstMatchSpec.builder()
+ .add({ $0.total >= 500 }, result: 100.0) // $100 off orders over $500
+ .add({ $0.itemCount >= 10 }, result: 50.0) // $50 off 10+ items
+ .add({ $0.customerTier == "VIP" }, result: 25.0) // $25 VIP discount
+ .fallback(0.0) // No discount
+ .build()
+
+let discount = discountSpec.decide(order) ?? 0.0
+```
+
+### Content Routing
+
+```swift
+let routingSpec = FirstMatchSpec.builder()
+ .add(
+ PredicateSpec.flag("maintenance_mode"),
+ result: "maintenance_page"
+ )
+ .add(
+ PredicateSpec.counter("onboarding_completed", .equal, 0),
+ result: "onboarding_flow"
+ )
+ .add(
+ PredicateSpec.flag("premium_user"),
+ result: "premium_dashboard"
+ )
+ .fallback("standard_dashboard")
+ .build()
+
+let route = routingSpec.decide(context) ?? "error_page"
+navigateTo(route)
+```
+
+### Feature Experiment Assignment
+
+```swift
+enum ExperimentVariant: String {
+ case control = "control"
+ case variantA = "variant_a"
+ case variantB = "variant_b"
+ case variantC = "variant_c"
+}
+
+let experimentSpec = FirstMatchSpec.builder()
+ .add(
+ BetaTesterSpec(),
+ result: .variantA
+ )
+ .add(
+ { user in user.id.hashValue % 3 == 0 },
+ result: .variantB
+ )
+ .add(
+ { user in user.id.hashValue % 3 == 1 },
+ result: .variantC
+ )
+ .fallback(.control)
+ .build()
+
+let variant = experimentSpec.decide(user) ?? .control
+```
+
+### Notification Priority
+
+```swift
+enum NotificationPriority {
+ case critical
+ case high
+ case normal
+ case low
+}
+
+let prioritySpec = FirstMatchSpec([
+ (SecurityAlertSpec(), .critical),
+ (PaymentDueSpec(), .high),
+ (MessageReceivedSpec(), .normal),
+ (NewsletterSpec(), .low)
+])
+
+if let priority = prioritySpec.decide(notification) {
+ sendNotification(notification, priority: priority)
+}
+```
+
+### Pricing Tier Selection
+
+```swift
+struct PricingTier {
+ let name: String
+ let monthlyPrice: Decimal
+ let features: [String]
+}
+
+let pricingSpec = FirstMatchSpec.builder()
+ .add(
+ EnterpriseContractSpec(),
+ result: PricingTier(
+ name: "Enterprise",
+ monthlyPrice: 999.99,
+ features: ["Unlimited", "Priority Support", "Custom Integration"]
+ )
+ )
+ .add(
+ TeamAccountSpec(),
+ result: PricingTier(
+ name: "Team",
+ monthlyPrice: 49.99,
+ features: ["Up to 25 users", "Standard Support"]
+ )
+ )
+ .add(
+ IndividualUserSpec(),
+ result: PricingTier(
+ name: "Pro",
+ monthlyPrice: 9.99,
+ features: ["Single user", "Email Support"]
+ )
+ )
+ .fallback(
+ PricingTier(
+ name: "Free",
+ monthlyPrice: 0.00,
+ features: ["Limited"]
+ )
+ )
+ .build()
+
+let tier = pricingSpec.decide(user)!
+```
+
+## Combining with Context
+
+Use with ``EvaluationContext`` for dynamic decisions:
+
+```swift
+let featureAccessSpec = FirstMatchSpec.builder()
+ .add(
+ PredicateSpec.flag("admin_access"),
+ result: ["admin", "premium", "standard", "basic"]
+ )
+ .add(
+ PredicateSpec.flag("premium_user"),
+ result: ["premium", "standard", "basic"]
+ )
+ .add(
+ PredicateSpec.counter("login_count", .greaterThan, 10),
+ result: ["standard", "basic"]
+ )
+ .fallback(["basic"])
+ .build()
+
+let provider = DefaultContextProvider.shared
+provider.setFlag("premium_user", to: true)
+
+let context = provider.currentContext()
+let features = featureAccessSpec.decide(context) ?? []
+```
+
+## Best Practices
+
+### Order Matters
+
+```swift
+// ✅ Good - most specific first
+let spec = FirstMatchSpec([
+ (VIPCustomerSpec(), "vip_service"), // Most specific
+ (PremiumUserSpec(), "premium_service"), // Less specific
+ (ActiveUserSpec(), "standard_service") // Least specific
+])
+
+// ❌ Wrong - general rules first prevent specific matches
+let badSpec = FirstMatchSpec([
+ (ActiveUserSpec(), "standard_service"), // Catches everyone
+ (PremiumUserSpec(), "premium_service"), // Never reached
+ (VIPCustomerSpec(), "vip_service") // Never reached
+])
+```
+
+### Always Provide Fallback for Critical Decisions
+
+```swift
+// ✅ Good - guaranteed result
+let spec = FirstMatchSpec.withFallback([
+ (PremiumSpec(), "premium_experience")
+], fallback: "default_experience")
+
+// ❌ Risky - might return nil
+let riskySpec = FirstMatchSpec([
+ (PremiumSpec(), "premium_experience")
+])
+
+// Need to handle nil
+let experience = riskySpec.decide(user) ?? "error"
+```
+
+### Use Builder for Complex Decisions
+
+```swift
+// ✅ Good - clear and maintainable
+let spec = FirstMatchSpec.builder()
+ .add(Spec1(), result: "result1")
+ .add(Spec2(), result: "result2")
+ .add(Spec3(), result: "result3")
+ .fallback("default")
+ .build()
+
+// ❌ Harder to read - array of tuples
+let spec = FirstMatchSpec([
+ (Spec1(), "result1"),
+ (Spec2(), "result2"),
+ (Spec3(), "result3"),
+ (AlwaysTrueSpec(), "default")
+])
+```
+
+### Type Consistency
+
+```swift
+// ✅ Good - consistent result types
+let spec = FirstMatchSpec([
+ (Spec1(), "option_a"),
+ (Spec2(), "option_b"),
+ (Spec3(), "option_c")
+])
+
+// Compiler enforces type consistency
+```
+
+## Performance Considerations
+
+- **Short-Circuit Evaluation**: Stops at first match; no unnecessary evaluations
+- **Order Optimization**: Place most likely matches first for better performance
+- **Metadata Overhead**: Minimal; only stores index when requested
+- **Builder Allocation**: Creates array; efficient for reasonable rule counts
+- **Type Erasure**: Uses `AnySpecification` internally; minimal overhead
+
+## Topics
+
+### Builder Pattern
+
+- ``Builder``
+- ``builder()``
+
+### Decision Methods
+
+- ``decide(_:)``
+
+## See Also
+
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/MaxCountSpec.md b/Sources/SpecificationCore/Documentation.docc/MaxCountSpec.md
new file mode 100644
index 0000000..a921ed5
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/MaxCountSpec.md
@@ -0,0 +1,525 @@
+# ``SpecificationCore/MaxCountSpec``
+
+A specification that checks if a counter is below a maximum threshold.
+
+## Overview
+
+`MaxCountSpec` is used to implement limits on actions, display counts, or usage restrictions. It evaluates to true when a counter value is strictly less than a specified maximum, making it ideal for rate limiting, usage quotas, and feature restrictions.
+
+### Key Benefits
+
+- **Simple Usage Limits**: Implement counters and quotas easily
+- **Context-Based**: Works with ``EvaluationContext`` counters
+- **Type-Safe**: Compile-time safety for counter keys and limits
+- **Flexible Variants**: Inclusive, exclusive, exact, and range checks
+- **Composable**: Combine with other specifications
+
+### When to Use MaxCountSpec
+
+Use `MaxCountSpec` when you need to:
+- Limit the number of times an action can be performed
+- Implement daily, weekly, or monthly quotas
+- Restrict feature usage based on tier or plan
+- Control banner or notification display frequency
+- Enforce API rate limits
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+// Set up context
+let provider = DefaultContextProvider.shared
+provider.setCounter("api_calls_today", to: 50)
+
+// Create spec with limit of 100
+let apiLimitSpec = MaxCountSpec(
+ counterKey: "api_calls_today",
+ maximumCount: 100
+)
+
+// Use with property wrapper
+@Satisfies(using: apiLimitSpec)
+var canMakeAPICall: Bool
+
+if canMakeAPICall {
+ makeAPICall()
+ provider.incrementCounter("api_calls_today")
+}
+```
+
+## Creating MaxCountSpec
+
+### Basic Creation
+
+```swift
+// Standard initialization
+let spec = MaxCountSpec(
+ counterKey: "login_attempts",
+ maximumCount: 5
+)
+
+// Alternative with "limit" parameter
+let spec2 = MaxCountSpec(
+ counterKey: "login_attempts",
+ limit: 5
+)
+
+// Both are equivalent
+```
+
+### Convenience Factories
+
+```swift
+// Generic counter limit
+let downloadLimit = MaxCountSpec.counter("downloads", limit: 10)
+
+// Single-use actions
+let showOnce = MaxCountSpec.onlyOnce("tutorial_shown")
+
+// Allow twice
+let allowTwice = MaxCountSpec.onlyTwice("password_reset")
+
+// Time-period limits
+let dailyLimit = MaxCountSpec.dailyLimit("api_calls", limit: 1000)
+let weeklyLimit = MaxCountSpec.weeklyLimit("reports_generated", limit: 50)
+let monthlyLimit = MaxCountSpec.monthlyLimit("exports", limit: 10)
+```
+
+## How It Works
+
+The specification checks if the counter is **strictly less than** the maximum:
+
+```swift
+let spec = MaxCountSpec(counterKey: "attempts", maximumCount: 3)
+
+// Counter = 0: satisfied (0 < 3) ✅
+// Counter = 1: satisfied (1 < 3) ✅
+// Counter = 2: satisfied (2 < 3) ✅
+// Counter = 3: NOT satisfied (3 < 3) ❌
+// Counter = 4: NOT satisfied (4 < 3) ❌
+```
+
+## Usage Examples
+
+### API Rate Limiting
+
+```swift
+let provider = DefaultContextProvider.shared
+
+// Set initial count
+provider.setCounter("api_requests", to: 0)
+
+// Create rate limit spec
+@Satisfies(using: MaxCountSpec(counterKey: "api_requests", maximumCount: 100))
+var canMakeRequest: Bool
+
+func makeAPIRequest() async throws -> Response {
+ guard canMakeRequest else {
+ throw APIError.rateLimitExceeded
+ }
+
+ let response = try await performRequest()
+ provider.incrementCounter("api_requests")
+ return response
+}
+
+// Reset daily
+func resetDailyLimits() {
+ provider.resetCounter("api_requests")
+}
+```
+
+### Feature Usage Limits
+
+```swift
+// Premium users: 100 exports per month
+// Free users: 5 exports per month
+
+let provider = DefaultContextProvider.shared
+let isPremium = // ... determine user tier
+
+let exportLimit = isPremium
+ ? MaxCountSpec.monthlyLimit("exports", limit: 100)
+ : MaxCountSpec.monthlyLimit("exports", limit: 5)
+
+@Satisfies(using: exportLimit)
+var canExport: Bool
+
+if canExport {
+ performExport()
+ provider.incrementCounter("exports")
+}
+```
+
+### Banner Display Limits
+
+```swift
+// Show promotional banner maximum 3 times
+let bannerSpec = MaxCountSpec.counter("promo_banner_shown", limit: 3)
+
+@Satisfies(using: bannerSpec)
+var shouldShowBanner: Bool
+
+struct ContentView: View {
+ var body: some View {
+ VStack {
+ if shouldShowBanner {
+ PromoBanner()
+ .onAppear {
+ DefaultContextProvider.shared
+ .incrementCounter("promo_banner_shown")
+ }
+ }
+ MainContent()
+ }
+ }
+}
+```
+
+### Trial Limits
+
+```swift
+// Free trial: 10 AI generations
+let trialSpec = MaxCountSpec(
+ counterKey: "ai_generations",
+ maximumCount: 10
+)
+
+@Satisfies(using: trialSpec)
+var canGenerateAI: Bool
+
+if canGenerateAI {
+ let result = generateAIContent()
+ provider.incrementCounter("ai_generations")
+ return result
+} else {
+ showUpgradePrompt()
+}
+```
+
+## Variant Specifications
+
+### Inclusive Maximum
+
+Allow values up to and including the maximum:
+
+```swift
+// Allow 0, 1, 2, 3, 4, 5 (inclusive)
+let inclusiveSpec = MaxCountSpec.inclusive(
+ counterKey: "attempts",
+ maximumCount: 5
+)
+
+// Counter = 5: satisfied (5 <= 5) ✅
+// Counter = 6: NOT satisfied (6 <= 5) ❌
+```
+
+### Exact Count
+
+Match an exact counter value:
+
+```swift
+// Satisfied only when counter equals 3
+let exactSpec = MaxCountSpec.exactly(
+ counterKey: "steps_completed",
+ count: 3
+)
+
+// Counter = 2: NOT satisfied ❌
+// Counter = 3: satisfied ✅
+// Counter = 4: NOT satisfied ❌
+```
+
+### Range Checks
+
+Check if counter is within a range:
+
+```swift
+// Satisfied when counter is between 10 and 20 (inclusive)
+let rangeSpec = MaxCountSpec.inRange(
+ counterKey: "items",
+ range: 10...20
+)
+
+// Counter = 9: NOT satisfied ❌
+// Counter = 15: satisfied ✅
+// Counter = 21: NOT satisfied ❌
+```
+
+## Composition
+
+Combine with other MaxCountSpecs or specifications:
+
+### AND Combination
+
+```swift
+// Both limits must be satisfied
+let multiLimit = MaxCountSpec(counterKey: "daily_requests", maximumCount: 100)
+ .and(MaxCountSpec(counterKey: "hourly_requests", maximumCount: 10))
+
+// Requires daily < 100 AND hourly < 10
+```
+
+### OR Combination
+
+```swift
+// Either limit can be satisfied
+let flexibleLimit = MaxCountSpec(counterKey: "free_tier_calls", maximumCount: 10)
+ .or(MaxCountSpec(counterKey: "premium_tier_calls", maximumCount: 1000))
+
+// Allows either counter to be under limit
+```
+
+### With Other Specifications
+
+```swift
+// Counter limit AND feature flag
+let combinedSpec = MaxCountSpec(counterKey: "feature_uses", maximumCount: 5)
+ .and(FeatureFlagSpec(flagKey: "feature_enabled"))
+
+// Must be under limit AND feature must be enabled
+```
+
+## Real-World Examples
+
+### Multi-Tier Access Control
+
+```swift
+enum UserTier {
+ case free, basic, premium, enterprise
+}
+
+func getAPILimitSpec(for tier: UserTier) -> MaxCountSpec {
+ switch tier {
+ case .free:
+ return MaxCountSpec.dailyLimit("api_calls", limit: 100)
+ case .basic:
+ return MaxCountSpec.dailyLimit("api_calls", limit: 1000)
+ case .premium:
+ return MaxCountSpec.dailyLimit("api_calls", limit: 10000)
+ case .enterprise:
+ return MaxCountSpec.dailyLimit("api_calls", limit: 100000)
+ }
+}
+
+let limitSpec = getAPILimitSpec(for: currentUserTier)
+
+@Satisfies(using: limitSpec)
+var canCallAPI: Bool
+```
+
+### Onboarding Flow
+
+```swift
+// Show onboarding only on first 3 app launches
+let onboardingSpec = MaxCountSpec.counter("app_launches", limit: 3)
+
+@Satisfies(using: onboardingSpec)
+var shouldShowOnboarding: Bool
+
+func application(_ application: UIApplication, didFinishLaunchingWithOptions...) {
+ DefaultContextProvider.shared.incrementCounter("app_launches")
+
+ if shouldShowOnboarding {
+ presentOnboarding()
+ }
+}
+```
+
+### Password Reset Limits
+
+```swift
+// Allow 3 password reset attempts per hour
+let resetLimitSpec = MaxCountSpec(
+ counterKey: "password_reset_attempts",
+ maximumCount: 3
+)
+
+@Satisfies(using: resetLimitSpec)
+var canResetPassword: Bool
+
+func requestPasswordReset() {
+ guard canResetPassword else {
+ showError("Too many reset attempts. Try again in an hour.")
+ return
+ }
+
+ sendPasswordResetEmail()
+ DefaultContextProvider.shared.incrementCounter("password_reset_attempts")
+}
+
+// Reset hourly
+Timer.scheduledTimer(withTimeInterval: 3600, repeats: true) { _ in
+ DefaultContextProvider.shared.resetCounter("password_reset_attempts")
+}
+```
+
+### Feature Rollout with Limits
+
+```swift
+// New feature limited to first 1000 users
+let betaAccessSpec = MaxCountSpec(
+ counterKey: "beta_users_enrolled",
+ maximumCount: 1000
+)
+
+@Satisfies(using: betaAccessSpec)
+var canEnrollInBeta: Bool
+
+func enrollInBeta() {
+ guard canEnrollInBeta else {
+ showAlert("Beta program is full")
+ return
+ }
+
+ enrollUser()
+ DefaultContextProvider.shared.incrementCounter("beta_users_enrolled")
+}
+```
+
+## Testing
+
+Test counter-based logic with ``MockContextProvider``:
+
+```swift
+func testAPIRateLimit() {
+ // Setup mock with counter at 99
+ let provider = MockContextProvider()
+ .withCounter("api_calls", value: 99)
+
+ let spec = MaxCountSpec(counterKey: "api_calls", maximumCount: 100)
+
+ // Should be satisfied (99 < 100)
+ XCTAssertTrue(spec.isSatisfiedBy(provider.currentContext()))
+
+ // Test at limit
+ let atLimit = MockContextProvider()
+ .withCounter("api_calls", value: 100)
+
+ // Should NOT be satisfied (100 < 100 is false)
+ XCTAssertFalse(spec.isSatisfiedBy(atLimit.currentContext()))
+}
+
+func testExactCount() {
+ let spec = MaxCountSpec.exactly(counterKey: "steps", count: 3)
+
+ // Not satisfied before reaching count
+ let before = MockContextProvider().withCounter("steps", value: 2)
+ XCTAssertFalse(spec.isSatisfiedBy(before.currentContext()))
+
+ // Satisfied at exact count
+ let exact = MockContextProvider().withCounter("steps", value: 3)
+ XCTAssertTrue(spec.isSatisfiedBy(exact.currentContext()))
+
+ // Not satisfied after exceeding count
+ let after = MockContextProvider().withCounter("steps", value: 4)
+ XCTAssertFalse(spec.isSatisfiedBy(after.currentContext()))
+}
+```
+
+## Best Practices
+
+### Choose Appropriate Limits
+
+```swift
+// ✅ Good - reasonable limits based on use case
+let apiLimit = MaxCountSpec.dailyLimit("api_calls", limit: 1000) // Generous
+let retryLimit = MaxCountSpec.counter("retries", limit: 3) // Conservative
+
+// ❌ Avoid - limits that don't match use case
+let tooRestrictive = MaxCountSpec.dailyLimit("page_views", limit: 1) // Too low
+let tooGenerous = MaxCountSpec.counter("login_attempts", limit: 1000) // Too high
+```
+
+### Reset Counters Appropriately
+
+```swift
+// ✅ Good - reset at appropriate intervals
+func resetDailyCounters() {
+ provider.resetCounter("daily_api_calls")
+ provider.resetCounter("daily_downloads")
+}
+
+Timer.scheduledTimer(withTimeInterval: 86400, repeats: true) { _ in
+ resetDailyCounters()
+}
+
+// ❌ Avoid - never resetting counters
+// Counters grow forever without reset
+```
+
+### Use Descriptive Counter Keys
+
+```swift
+// ✅ Good - clear, specific keys
+let spec1 = MaxCountSpec.counter("password_reset_attempts_today", limit: 3)
+let spec2 = MaxCountSpec.counter("api_calls_per_hour", limit: 100)
+
+// ❌ Avoid - ambiguous keys
+let spec3 = MaxCountSpec.counter("count", limit: 3) // What count?
+let spec4 = MaxCountSpec.counter("limit", limit: 100) // Confusing
+```
+
+### Handle Counter Overflow Gracefully
+
+```swift
+// ✅ Good - check before incrementing
+if canPerformAction {
+ performAction()
+ provider.incrementCounter("actions")
+} else {
+ handleLimitReached()
+}
+
+// ❌ Avoid - increment without checking
+performAction()
+provider.incrementCounter("actions") // Might exceed limit
+```
+
+## Performance Considerations
+
+- **Dictionary Lookup**: O(1) counter access from context
+- **No Side Effects**: Read-only evaluation; no state modification
+- **Missing Counters**: Returns 0 if counter doesn't exist; no overhead
+- **Composition**: Each composition creates new specification; efficient
+- **Context Creation**: Provider creates context on each call; lightweight operation
+
+## Topics
+
+### Creating Specifications
+
+- ``init(counterKey:maximumCount:)``
+- ``init(counterKey:limit:)``
+
+### Convenience Factories
+
+- ``counter(_:limit:)``
+- ``onlyOnce(_:)``
+- ``onlyTwice(_:)``
+- ``dailyLimit(_:limit:)``
+- ``weeklyLimit(_:limit:)``
+- ``monthlyLimit(_:limit:)``
+
+### Variant Specifications
+
+- ``inclusive(counterKey:maximumCount:)``
+- ``exactly(counterKey:count:)``
+- ``inRange(counterKey:range:)``
+
+### Composition
+
+- ``and(_:)``
+- ``or(_:)``
+
+### Properties
+
+- ``counterKey``
+- ``maximumCount``
+
+## See Also
+
+-
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/Maybe.md b/Sources/SpecificationCore/Documentation.docc/Maybe.md
new file mode 100644
index 0000000..96828c0
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Maybe.md
@@ -0,0 +1,682 @@
+# ``SpecificationCore/Maybe``
+
+A property wrapper that evaluates decision specifications and returns an optional result without requiring a fallback.
+
+## Overview
+
+`@Maybe` is the optional counterpart to ``Decides``. It evaluates decision specifications and returns the result if a specification is satisfied, or `nil` if no specification matches. This is ideal when you want to explicitly handle the "no match" case without providing a default value.
+
+### Key Benefits
+
+- **Optional Results**: Returns `nil` when no specification matches instead of requiring a fallback
+- **Priority-Based**: Uses first-match-wins logic like ``Decides``
+- **Type-Safe**: Generic over both context and result types
+- **No Fallback Required**: Cleaner API when you want to handle `nil` explicitly
+- **Flexible Patterns**: Supports arrays, decision specs, and custom logic
+- **Builder Support**: Create complex decision trees with fluent API
+
+### When to Use @Maybe
+
+Use `@Maybe` when you need to:
+- Detect when no specification matched (explicitly handle `nil`)
+- Provide optional features or enhancements
+- Conditionally apply logic only when criteria are met
+- Distinguish between "no match" and a default value
+- Implement optional routing or content variants
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+// Optional theme based on conditions
+@Maybe([
+ (PremiumUserSpec(), "premium_theme"),
+ (HolidaySeasonSpec(), "holiday_theme"),
+ (BetaUserSpec(), "experimental_theme")
+])
+var specialTheme: String?
+
+// Usage
+if let theme = specialTheme {
+ applyTheme(theme)
+} else {
+ useDefaultTheme()
+}
+```
+
+## Creating @Maybe
+
+### With Specification-Result Pairs
+
+```swift
+// Array of (Specification, Result) pairs
+@Maybe([
+ (FirstTimeUserSpec(), 0.20), // 20% for new users
+ (VIPMemberSpec(), 0.15), // 15% for VIP
+ (FlashSaleSpec(), 0.10) // 10% during flash sale
+])
+var discount: Double?
+
+let finalPrice = originalPrice * (1.0 - (discount ?? 0.0))
+```
+
+### With DecisionSpec Instance
+
+```swift
+let personalizationSpec = FirstMatchSpec([
+ (UserPreferenceSpec(theme: .dark), "dark_mode_content"),
+ (TimeOfDaySpec(after: 18), "evening_content"),
+ (WeatherConditionSpec(.rainy), "cozy_content")
+])
+
+@Maybe(using: personalizationSpec)
+var personalizedContent: String?
+```
+
+### With Custom Decision Logic
+
+```swift
+@Maybe(decide: { context in
+ let score = context.counter(for: "engagement_score")
+ guard score > 0 else { return nil }
+
+ switch score {
+ case 90...100: return "gold_badge"
+ case 70...89: return "silver_badge"
+ case 50...69: return "bronze_badge"
+ default: return nil
+ }
+})
+var achievementBadge: String?
+```
+
+## How It Works
+
+The wrapper evaluates specifications in order and returns the first match or `nil`:
+
+```swift
+@Maybe([
+ (Spec1(), "result1"), // Checked first
+ (Spec2(), "result2"), // Checked second
+ (Spec3(), "result3") // Checked third
+])
+var result: String?
+
+// Evaluation logic:
+// 1. If Spec1 matches → returns "result1"
+// 2. Else if Spec2 matches → returns "result2"
+// 3. Else if Spec3 matches → returns "result3"
+// 4. Else → returns nil
+```
+
+## Usage Examples
+
+### Optional Feature Selection
+
+```swift
+@Maybe([
+ (ABTestVariantASpec(), "variant_a_feature"),
+ (ABTestVariantBSpec(), "variant_b_feature")
+])
+var experimentalFeature: String?
+
+func setupFeatures() {
+ // Only enable if user is in experiment
+ if let feature = experimentalFeature {
+ enableFeature(feature)
+ }
+ // If nil, skip experimental features entirely
+}
+```
+
+### Conditional Discounts
+
+```swift
+@Maybe([
+ (LoyaltyRewardSpec(), 30.0), // 30% loyalty reward
+ (ReferralDiscountSpec(), 20.0), // 20% referral
+ (SeasonalPromotionSpec(), 15.0) // 15% seasonal
+])
+var promotionalDiscount: Double?
+
+func calculatePrice(basePrice: Double) -> Double {
+ if let discount = promotionalDiscount {
+ return basePrice * (1.0 - discount / 100.0)
+ }
+ return basePrice // No discount applied
+}
+```
+
+### Optional Content Routing
+
+```swift
+@Maybe([
+ (RegionalContentSpec(region: "EU"), "eu_gdpr_content"),
+ (RegionalContentSpec(region: "CA"), "canada_content"),
+ (RegionalContentSpec(region: "UK"), "uk_content")
+])
+var regionalContent: String?
+
+let contentToShow = regionalContent ?? standardGlobalContent
+```
+
+### Achievement System
+
+```swift
+@Maybe(decide: { context in
+ let completedTasks = context.counter(for: "completed_tasks")
+ let perfectScore = context.flag(for: "perfect_score")
+ let speedBonus = context.flag(for: "speed_bonus")
+
+ if perfectScore && speedBonus {
+ return "legendary_achievement"
+ } else if completedTasks >= 100 {
+ return "master_achievement"
+ } else if completedTasks >= 50 {
+ return "expert_achievement"
+ } else if completedTasks >= 10 {
+ return "novice_achievement"
+ }
+
+ return nil // No achievement yet
+})
+var currentAchievement: String?
+```
+
+### Personalization Engine
+
+```swift
+@Maybe([
+ (UserSegmentSpec(segment: "power_user"), "advanced_dashboard"),
+ (UserSegmentSpec(segment: "new_user"), "guided_dashboard"),
+ (UserSegmentSpec(segment: "returning_user"), "quick_access_dashboard")
+])
+var customDashboard: String?
+
+func loadDashboard() {
+ if let dashboard = customDashboard {
+ loadCustomDashboard(dashboard)
+ analytics.track("custom_dashboard_loaded", ["type": dashboard])
+ } else {
+ loadStandardDashboard()
+ analytics.track("standard_dashboard_loaded")
+ }
+}
+```
+
+## Comparison with @Decides
+
+The key difference is how they handle "no match":
+
+```swift
+// @Maybe - returns nil when no specification matches
+@Maybe([
+ (PremiumUserSpec(), "premium_feature")
+])
+var optionalFeature: String? // Can be nil
+
+if let feature = optionalFeature {
+ enableFeature(feature) // Only runs if spec matched
+}
+
+// @Decides - always returns a value with fallback
+@Decides([
+ (PremiumUserSpec(), "premium_feature")
+], or: "basic_feature")
+var guaranteedFeature: String // Never nil
+
+let feature = guaranteedFeature // Always has a value
+enableFeature(feature)
+```
+
+When to use which:
+
+- **Use @Maybe** when `nil` has meaning (feature disabled, no match, skip logic)
+- **Use @Decides** when you always need a value (routing, tier selection, configuration)
+
+## Real-World Examples
+
+### Promotional Banner System
+
+```swift
+class BannerManager {
+ @Maybe([
+ (DateRangeSpec(start: blackFridayStart, end: blackFridayEnd), "black_friday_banner"),
+ (DateRangeSpec(start: cyberMondayStart, end: cyberMondayEnd), "cyber_monday_banner"),
+ (NewUserSpec(), "welcome_banner"),
+ (InactiveUserSpec(), "comeback_banner")
+ ])
+ var activeBanner: String?
+
+ func updateUI() {
+ if let banner = activeBanner {
+ showBanner(banner)
+ trackBannerImpression(banner)
+ } else {
+ hideBannerArea()
+ }
+ }
+}
+```
+
+### Feature Upgrade Prompt
+
+```swift
+struct UpgradePromptManager {
+ enum PromptType {
+ case urgentUpgrade
+ case softUpsell
+ case featureAwareness
+
+ var message: String {
+ switch self {
+ case .urgentUpgrade:
+ return "Upgrade now to continue using premium features"
+ case .softUpsell:
+ return "Unlock more features with premium"
+ case .featureAwareness:
+ return "Did you know premium users get..."
+ }
+ }
+
+ var priority: Int {
+ switch self {
+ case .urgentUpgrade: return 3
+ case .softUpsell: return 2
+ case .featureAwareness: return 1
+ }
+ }
+ }
+
+ @Maybe(decide: { context in
+ let isFreeTier = context.flag(for: "free_tier")
+ let trialExpired = context.flag(for: "trial_expired")
+ let usageCount = context.counter(for: "premium_feature_attempts")
+
+ if trialExpired {
+ return PromptType.urgentUpgrade
+ } else if isFreeTier && usageCount >= 5 {
+ return PromptType.softUpsell
+ } else if isFreeTier && usageCount >= 2 {
+ return PromptType.featureAwareness
+ }
+
+ return nil // Don't show prompt
+ })
+ var upgradePrompt: PromptType?
+
+ func checkAndShowPrompt() {
+ guard let prompt = upgradePrompt else {
+ return // No prompt needed
+ }
+
+ showUpgradePrompt(message: prompt.message, priority: prompt.priority)
+ }
+}
+```
+
+### Contextual Help System
+
+```swift
+class HelpSystemManager {
+ struct HelpContext {
+ let screen: String
+ let topic: String
+ let priority: Int
+ }
+
+ @Maybe(decide: { context in
+ let currentScreen = context.userData["current_screen"] as? String ?? ""
+ let sessionDuration = context.timeSinceLaunch
+
+ // Show help after 30 seconds on complex screens
+ switch currentScreen {
+ case "advanced_settings":
+ if sessionDuration > 30 {
+ return HelpContext(
+ screen: "advanced_settings",
+ topic: "settings_guide",
+ priority: 2
+ )
+ }
+ case "first_time_setup":
+ return HelpContext(
+ screen: "first_time_setup",
+ topic: "getting_started",
+ priority: 3
+ )
+ case "payment_screen":
+ if sessionDuration > 60 {
+ return HelpContext(
+ screen: "payment",
+ topic: "payment_help",
+ priority: 3
+ )
+ }
+ default:
+ break
+ }
+
+ return nil // No help needed
+ })
+ var contextualHelp: HelpContext?
+
+ func updateHelpOverlay() {
+ if let help = contextualHelp {
+ showHelpButton(for: help.topic, priority: help.priority)
+ } else {
+ hideHelpButton()
+ }
+ }
+}
+```
+
+### Email Notification Selector
+
+```swift
+class EmailNotificationManager {
+ enum EmailTemplate {
+ case welcomeSeries
+ case productUpdate
+ case specialOffer
+ case reEngagement
+
+ var templateId: String {
+ switch self {
+ case .welcomeSeries: return "welcome_email_v2"
+ case .productUpdate: return "product_update_template"
+ case .specialOffer: return "special_offer_template"
+ case .reEngagement: return "re_engagement_email"
+ }
+ }
+
+ var sendDelay: TimeInterval {
+ switch self {
+ case .welcomeSeries: return 0
+ case .productUpdate: return 3600
+ case .specialOffer: return 0
+ case .reEngagement: return 86400
+ }
+ }
+ }
+
+ @Maybe([
+ (TimeSinceEventSpec(eventKey: "user_registered", hours: 1), EmailTemplate.welcomeSeries),
+ (FeatureFlagSpec(flagKey: "new_product_launch"), EmailTemplate.productUpdate),
+ (DateRangeSpec(start: promotionStart, end: promotionEnd), EmailTemplate.specialOffer),
+ (TimeSinceEventSpec(eventKey: "last_login", days: 30), EmailTemplate.reEngagement)
+ ])
+ var pendingEmail: EmailTemplate?
+
+ func processEmailQueue() {
+ guard let email = pendingEmail else {
+ return // No emails to send
+ }
+
+ scheduleEmail(
+ template: email.templateId,
+ delay: email.sendDelay
+ )
+
+ // Record that we sent this email
+ DefaultContextProvider.shared
+ .recordEvent("email_sent_\(email.templateId)")
+ }
+}
+```
+
+## Builder Pattern
+
+Create complex optional decisions with the builder API:
+
+```swift
+let contentBuilder = Maybe.builder(
+ provider: DefaultContextProvider.shared
+)
+
+let wrappedValue = contentBuilder
+ .with(HolidaySpec(), result: "holiday_content")
+ .with(BirthdaySpec(), result: "birthday_content")
+ .with(NewUserSpec(), result: "welcome_content")
+ .build()
+
+@Maybe(using: wrappedValue)
+var specialContent: String?
+```
+
+## Projected Value
+
+Both `wrappedValue` and `projectedValue` return the same optional result:
+
+```swift
+@Maybe([
+ (SpecialEventSpec(), "special_event_theme")
+])
+var eventTheme: String?
+
+// Both provide the same value
+let theme1 = eventTheme
+let theme2 = $eventTheme
+
+// Both are nil if no spec matches
+if theme1 == nil && theme2 == nil {
+ print("No special theme active")
+}
+```
+
+## Testing
+
+Test optional decision logic with ``MockContextProvider``:
+
+```swift
+func testOptionalFeature() {
+ let provider = MockContextProvider()
+
+ @Maybe(
+ provider: provider,
+ firstMatch: [
+ (FeatureFlagSpec(flagKey: "special_feature"), "special")
+ ]
+ )
+ var feature: String?
+
+ // No flag set - should be nil
+ XCTAssertNil(feature)
+
+ // Enable flag - should return result
+ provider.setFlag("special_feature", to: true)
+ XCTAssertEqual(feature, "special")
+
+ // Disable flag - should be nil again
+ provider.setFlag("special_feature", to: false)
+ XCTAssertNil(feature)
+}
+
+func testDecisionPriority() {
+ let provider = MockContextProvider()
+ .withFlag("premium", value: true)
+ .withFlag("beta", value: true)
+
+ @Maybe(
+ provider: provider,
+ firstMatch: [
+ (FeatureFlagSpec(flagKey: "premium"), "premium_content"),
+ (FeatureFlagSpec(flagKey: "beta"), "beta_content")
+ ]
+ )
+ var content: String?
+
+ // Premium has priority over beta
+ XCTAssertEqual(content, "premium_content")
+
+ // Disable premium, beta should now match
+ provider.setFlag("premium", to: false)
+ XCTAssertEqual(content, "beta_content")
+
+ // Disable both, should be nil
+ provider.setFlag("beta", to: false)
+ XCTAssertNil(content)
+}
+
+func testCustomDecision() {
+ let provider = MockContextProvider()
+ .withCounter("score", value: 85)
+
+ @Maybe(
+ provider: provider,
+ decide: { context in
+ let score = context.counter(for: "score")
+ if score >= 90 {
+ return "gold"
+ } else if score >= 70 {
+ return "silver"
+ } else if score >= 50 {
+ return "bronze"
+ }
+ return nil
+ }
+ )
+ var badge: String?
+
+ XCTAssertEqual(badge, "silver")
+
+ provider.setCounter("score", to: 95)
+ XCTAssertEqual(badge, "gold")
+
+ provider.setCounter("score", to: 30)
+ XCTAssertNil(badge)
+}
+```
+
+## Best Practices
+
+### Order Specifications Correctly
+
+```swift
+// ✅ Good - most specific first
+@Maybe([
+ (VIPEventSpec(), "exclusive_vip_content"),
+ (PremiumEventSpec(), "premium_content"),
+ (PublicEventSpec(), "public_content")
+])
+var eventContent: String?
+
+// ❌ Avoid - wrong order
+@Maybe([
+ (PublicEventSpec(), "public_content"), // Too broad
+ (PremiumEventSpec(), "premium_content"),
+ (VIPEventSpec(), "exclusive_vip_content")
+])
+var badContent: String? // VIP users get public content!
+```
+
+### Handle Nil Appropriately
+
+```swift
+// ✅ Good - explicit nil handling
+@Maybe([
+ (PromoCodeSpec(), "promo_banner")
+])
+var banner: String?
+
+if let bannerType = banner {
+ showBanner(bannerType)
+} else {
+ // Explicitly handle no banner case
+ hidePromotionalSection()
+}
+
+// ✅ Good - nil coalescing with default
+let contentVariant = banner ?? "default_banner"
+
+// ⚠️ Consider - force unwrapping risks
+// let content = banner! // Crashes if nil!
+```
+
+### Use Type-Safe Results
+
+```swift
+// ✅ Good - enum for type safety
+enum BadgeLevel {
+ case platinum, gold, silver, bronze
+}
+
+@Maybe([
+ (HighScoreSpec(), BadgeLevel.platinum),
+ (GoodScoreSpec(), BadgeLevel.gold),
+ (AverageScoreSpec(), BadgeLevel.silver)
+])
+var earnedBadge: BadgeLevel?
+
+// ❌ Avoid - error-prone strings
+@Maybe([
+ (HighScoreSpec(), "platinum"),
+ (GoodScoreSpec(), "gold")
+])
+var badgeString: String? // Typo-prone
+```
+
+### Distinguish from Fallback Scenarios
+
+```swift
+// Use @Maybe when nil means "don't do anything"
+@Maybe([
+ (SpecialEventSpec(), "event_theme")
+])
+var optionalTheme: String?
+
+if let theme = optionalTheme {
+ applyTheme(theme)
+}
+// If nil, don't apply any theme
+
+// Use @Decides when you always need a value
+@Decides([
+ (SpecialEventSpec(), "event_theme")
+], or: "default_theme")
+var guaranteedTheme: String
+
+applyTheme(guaranteedTheme) // Always applies a theme
+```
+
+## Performance Considerations
+
+- **First-Match Evaluation**: Stops at first satisfied specification
+- **Order Matters**: Place most likely matches first for better performance
+- **No Fallback Overhead**: Slightly faster than ``Decides`` (no fallback evaluation)
+- **Context Fetching**: Context retrieved once per property access
+- **Nil Check Cost**: Minimal overhead for optional handling
+- **Re-Evaluation**: No caching; evaluates on each access
+
+## Topics
+
+### Creating Property Wrappers
+
+- ``init(provider:using:)``
+- ``init(provider:firstMatch:)``
+- ``init(provider:decide:)``
+
+### Convenience Initializers
+
+- ``init(using:)``
+- ``init(_:)``
+- ``init(decide:)``
+
+### Builder Pattern
+
+- ``builder(provider:)``
+- ``MaybeBuilder``
+
+### Property Values
+
+- ``wrappedValue``
+- ``projectedValue``
+
+## See Also
+
+-
+-
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/MockContextProvider.md b/Sources/SpecificationCore/Documentation.docc/MockContextProvider.md
new file mode 100644
index 0000000..73b852e
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/MockContextProvider.md
@@ -0,0 +1,627 @@
+# ``SpecificationCore/MockContextProvider``
+
+A mock context provider designed for unit testing specifications.
+
+## Overview
+
+`MockContextProvider` allows you to set up specific context scenarios and verify that specifications behave correctly under controlled conditions. It provides builder-style configuration, request tracking, and pre-configured test scenarios.
+
+### Key Features
+
+- **Controllable Context**: Set exact context state for testing
+- **Request Tracking**: Monitor how many times context is requested
+- **Builder Pattern**: Fluent interface for configuration
+- **Test Scenarios**: Pre-configured helpers for common test cases
+- **Verification**: Built-in methods to assert expected behavior
+
+### When to Use MockContextProvider
+
+Use `MockContextProvider` when you need to:
+- Unit test specifications with controlled context
+- Verify specification behavior under specific conditions
+- Test edge cases and boundary conditions
+- Track context access in tests
+- Create reproducible test scenarios
+
+## Quick Example
+
+```swift
+import SpecificationCore
+import XCTest
+
+class FeatureSpecTests: XCTestCase {
+ func testPremiumFeature() {
+ // Create mock provider with specific state
+ let provider = MockContextProvider()
+ .withFlag("premium", value: true)
+ .withCounter("usage", value: 5)
+
+ let context = provider.currentContext()
+
+ // Test specification
+ let spec = PremiumFeatureSpec()
+ XCTAssertTrue(spec.isSatisfiedBy(context))
+ }
+}
+```
+
+## Creating Mock Providers
+
+### Default Initialization
+
+```swift
+// Empty context
+let provider = MockContextProvider()
+
+// With specific context
+let context = EvaluationContext(
+ flags: ["test_mode": true],
+ counters: ["attempts": 3]
+)
+let provider = MockContextProvider(context: context)
+
+// With builder parameters
+let provider = MockContextProvider(
+ currentDate: Date(),
+ flags: ["premium": true],
+ counters: ["usage": 10]
+)
+```
+
+### Setting Initial Context
+
+```swift
+// Configure after creation
+let provider = MockContextProvider()
+
+let testContext = EvaluationContext(
+ flags: ["feature_enabled": true],
+ counters: ["api_calls": 50]
+)
+
+provider.setContext(testContext)
+```
+
+## Builder Pattern
+
+Chain configuration methods for fluent setup:
+
+### Adding Flags
+
+```swift
+let provider = MockContextProvider()
+ .withFlag("premium", value: true)
+ .withFlag("beta_tester", value: true)
+ .withFlag("analytics", value: false)
+
+// Or set multiple at once
+let provider2 = MockContextProvider()
+ .withFlags([
+ "premium": true,
+ "beta": true
+ ])
+```
+
+### Adding Counters
+
+```swift
+let provider = MockContextProvider()
+ .withCounter("login_attempts", value: 3)
+ .withCounter("api_calls", value: 100)
+ .withCounter("page_views", value: 50)
+
+// Or set multiple at once
+let provider2 = MockContextProvider()
+ .withCounters([
+ "attempts": 3,
+ "calls": 100
+ ])
+```
+
+### Adding Events
+
+```swift
+let lastLogin = Date().addingTimeInterval(-3600) // 1 hour ago
+let lastPurchase = Date().addingTimeInterval(-86400) // 1 day ago
+
+let provider = MockContextProvider()
+ .withEvent("last_login", date: lastLogin)
+ .withEvent("last_purchase", date: lastPurchase)
+
+// Or set multiple at once
+let provider2 = MockContextProvider()
+ .withEvents([
+ "last_login": lastLogin,
+ "last_purchase": lastPurchase
+ ])
+```
+
+### Adding User Data
+
+```swift
+struct UserProfile {
+ let tier: String
+ let verified: Bool
+}
+
+let profile = UserProfile(tier: "premium", verified: true)
+
+let provider = MockContextProvider()
+ .withUserData([
+ "user_profile": profile,
+ "user_id": "test-123"
+ ])
+```
+
+### Setting Timestamps
+
+```swift
+let testDate = Date(timeIntervalSince1970: 1640000000)
+
+let provider = MockContextProvider()
+ .withCurrentDate(testDate)
+```
+
+## Request Tracking
+
+Monitor context access in tests:
+
+```swift
+let provider = MockContextProvider()
+ .withFlag("feature", value: true)
+
+// Track requests
+XCTAssertEqual(provider.contextRequestCount, 0)
+
+let context1 = provider.currentContext()
+XCTAssertEqual(provider.contextRequestCount, 1)
+
+let context2 = provider.currentContext()
+XCTAssertEqual(provider.contextRequestCount, 2)
+
+// Verify expected count
+XCTAssertTrue(provider.verifyContextRequestCount(2))
+
+// Reset tracking
+provider.resetRequestCount()
+XCTAssertEqual(provider.contextRequestCount, 0)
+```
+
+### Request Callbacks
+
+Get notified when context is requested:
+
+```swift
+var requestLog: [Date] = []
+
+let provider = MockContextProvider()
+provider.onContextRequested = {
+ requestLog.append(Date())
+}
+
+// Each request triggers callback
+provider.currentContext()
+provider.currentContext()
+
+XCTAssertEqual(requestLog.count, 2)
+```
+
+## Pre-Configured Test Scenarios
+
+Use helper methods for common test cases:
+
+### Launch Delay Scenarios
+
+Test time-since-launch behavior:
+
+```swift
+// Simulate app running for 5 minutes
+let provider = MockContextProvider.launchDelayScenario(
+ timeSinceLaunch: 300 // seconds
+)
+
+let context = provider.currentContext()
+XCTAssertEqual(context.timeSinceLaunch, 300)
+
+// Use with time-based specs
+let spec = MinimumRuntimeSpec(minimumSeconds: 60)
+XCTAssertTrue(spec.isSatisfiedBy(context))
+```
+
+### Counter Scenarios
+
+Test counter-based specifications:
+
+```swift
+// Setup specific counter value
+let provider = MockContextProvider.counterScenario(
+ counterKey: "api_calls",
+ counterValue: 95
+)
+
+let context = provider.currentContext()
+XCTAssertEqual(context.counter(for: "api_calls"), 95)
+
+// Test with MaxCountSpec
+let spec = MaxCountSpec(counterKey: "api_calls", maximumCount: 100)
+XCTAssertTrue(spec.isSatisfiedBy(context)) // 95 < 100
+```
+
+### Cooldown Scenarios
+
+Test cooldown and time-based specs:
+
+```swift
+// Simulate event that occurred 30 minutes ago
+let provider = MockContextProvider.cooldownScenario(
+ eventKey: "last_notification",
+ timeSinceEvent: 1800 // 30 minutes in seconds
+)
+
+let context = provider.currentContext()
+let timeSince = context.timeSinceEvent("last_notification")
+XCTAssertEqual(timeSince, 1800)
+
+// Test cooldown spec
+let spec = CooldownIntervalSpec(
+ eventKey: "last_notification",
+ interval: 3600 // 1 hour cooldown
+)
+XCTAssertFalse(spec.isSatisfiedBy(context)) // 1800 < 3600
+```
+
+## Testing Specifications
+
+### Basic Specification Testing
+
+```swift
+func testAdultUserSpec() {
+ // Setup context
+ let provider = MockContextProvider()
+ .withFlag("adult_verified", value: true)
+
+ let context = provider.currentContext()
+
+ // Test spec
+ let spec = AdultVerificationSpec()
+ XCTAssertTrue(spec.isSatisfiedBy(context))
+}
+```
+
+### Testing Edge Cases
+
+```swift
+func testMaxCountBoundary() {
+ // Test exactly at limit
+ let atLimit = MockContextProvider()
+ .withCounter("attempts", value: 5)
+
+ let spec = MaxCountSpec(counterKey: "attempts", maximumCount: 5)
+ XCTAssertTrue(spec.isSatisfiedBy(atLimit.currentContext()))
+
+ // Test over limit
+ let overLimit = MockContextProvider()
+ .withCounter("attempts", value: 6)
+
+ XCTAssertFalse(spec.isSatisfiedBy(overLimit.currentContext()))
+}
+```
+
+### Testing Multiple Conditions
+
+```swift
+func testComplexEligibility() {
+ let provider = MockContextProvider()
+ .withFlag("premium", value: true)
+ .withCounter("usage", value: 10)
+ .withEvent("last_action", date: Date().addingTimeInterval(-7200))
+
+ let context = provider.currentContext()
+
+ let spec = EligibilitySpec()
+ XCTAssertTrue(spec.isSatisfiedBy(context))
+}
+```
+
+## Testing with Property Wrappers
+
+Test property wrapper behavior:
+
+```swift
+func testSatisfiesWrapper() {
+ let provider = MockContextProvider()
+ .withFlag("feature_enabled", value: true)
+
+ struct ViewModel {
+ let context: EvaluationContext
+
+ @Satisfies(using: FeatureFlagSpec(flagKey: "feature_enabled"))
+ var isEnabled: Bool
+
+ init(context: EvaluationContext) {
+ self.context = context
+ _isEnabled = Satisfies(
+ using: FeatureFlagSpec(flagKey: "feature_enabled"),
+ with: context
+ )
+ }
+ }
+
+ let viewModel = ViewModel(context: provider.currentContext())
+ XCTAssertTrue(viewModel.isEnabled)
+}
+```
+
+## Testing Decision Specs
+
+Test specifications that return typed results:
+
+```swift
+func testDiscountDecision() {
+ let provider = MockContextProvider()
+ .withFlag("is_premium", value: true)
+
+ let context = provider.currentContext()
+
+ struct DiscountSpec: DecisionSpec {
+ func decide(_ context: EvaluationContext) -> String? {
+ context.flag(for: "is_premium") ? "PREMIUM20" : nil
+ }
+ }
+
+ let spec = DiscountSpec()
+ let discount = spec.decide(context)
+
+ XCTAssertEqual(discount, "PREMIUM20")
+}
+```
+
+## Parameterized Testing
+
+Use mock providers for data-driven tests:
+
+```swift
+func testCounterLimits() {
+ let testCases: [(count: Int, shouldPass: Bool)] = [
+ (0, true),
+ (5, true),
+ (10, true),
+ (11, false),
+ (100, false)
+ ]
+
+ let spec = MaxCountSpec(counterKey: "attempts", maximumCount: 10)
+
+ for testCase in testCases {
+ let provider = MockContextProvider()
+ .withCounter("attempts", value: testCase.count)
+
+ let result = spec.isSatisfiedBy(provider.currentContext())
+
+ XCTAssertEqual(
+ result,
+ testCase.shouldPass,
+ "Failed for count: \(testCase.count)"
+ )
+ }
+}
+```
+
+## Testing Time-Based Logic
+
+Control time for deterministic tests:
+
+```swift
+func testDateRange() {
+ let startDate = Date(timeIntervalSince1970: 1640000000)
+ let endDate = startDate.addingTimeInterval(86400) // +1 day
+
+ // Test within range
+ let withinRange = MockContextProvider()
+ .withCurrentDate(startDate.addingTimeInterval(43200)) // Midpoint
+
+ let spec = DateRangeSpec(start: startDate, end: endDate)
+ XCTAssertTrue(spec.isSatisfiedBy(withinRange.currentContext()))
+
+ // Test outside range
+ let outsideRange = MockContextProvider()
+ .withCurrentDate(endDate.addingTimeInterval(1)) // Past end
+
+ XCTAssertFalse(spec.isSatisfiedBy(outsideRange.currentContext()))
+}
+```
+
+## Testing Composition
+
+Test complex specification compositions:
+
+```swift
+func testComposedSpecs() {
+ let provider = MockContextProvider()
+ .withFlag("premium", value: true)
+ .withCounter("usage", value: 5)
+ .withEvent("last_action", date: Date().addingTimeInterval(-7200))
+
+ let premiumSpec = FeatureFlagSpec(flagKey: "premium")
+ let usageSpec = MaxCountSpec(counterKey: "usage", maximumCount: 10)
+ let cooldownSpec = CooldownIntervalSpec(
+ eventKey: "last_action",
+ interval: 3600
+ )
+
+ // Test individual specs
+ let context = provider.currentContext()
+ XCTAssertTrue(premiumSpec.isSatisfiedBy(context))
+ XCTAssertTrue(usageSpec.isSatisfiedBy(context))
+ XCTAssertTrue(cooldownSpec.isSatisfiedBy(context))
+
+ // Test composition
+ let combined = premiumSpec && usageSpec && cooldownSpec
+ XCTAssertTrue(combined.isSatisfiedBy(context))
+}
+```
+
+## Verifying Behavior
+
+Verify specifications handle various scenarios:
+
+```swift
+func testSpecHandlesMissingData() {
+ // Empty context - no flags, counters, or events
+ let empty = MockContextProvider()
+
+ let context = empty.currentContext()
+
+ // Verify spec handles missing data gracefully
+ let spec = FeatureFlagSpec(flagKey: "nonexistent")
+ XCTAssertFalse(spec.isSatisfiedBy(context)) // Should default to false
+
+ let counterSpec = MaxCountSpec(counterKey: "missing", maximumCount: 10)
+ XCTAssertTrue(counterSpec.isSatisfiedBy(context)) // 0 < 10
+}
+```
+
+## Integration Testing
+
+Use mock providers for integration tests:
+
+```swift
+func testFeatureService() {
+ // Setup mock provider
+ let provider = MockContextProvider()
+ .withFlag("feature_a", value: true)
+ .withFlag("feature_b", value: false)
+
+ // Inject into service
+ let service = FeatureService(contextProvider: provider)
+
+ // Test service behavior
+ XCTAssertTrue(service.isFeatureAEnabled())
+ XCTAssertFalse(service.isFeatureBEnabled())
+
+ // Verify context was accessed
+ XCTAssertEqual(provider.contextRequestCount, 2)
+}
+```
+
+## Best Practices
+
+### Create Fresh Providers for Each Test
+
+```swift
+// ✅ Good - isolated test state
+class SpecTests: XCTestCase {
+ func testScenario1() {
+ let provider = MockContextProvider()
+ .withFlag("test", value: true)
+ // Test with this provider
+ }
+
+ func testScenario2() {
+ let provider = MockContextProvider()
+ .withFlag("test", value: false)
+ // Test with this provider
+ }
+}
+
+// ❌ Avoid - shared state between tests
+class SpecTests: XCTestCase {
+ let provider = MockContextProvider() // Shared!
+
+ func testScenario1() {
+ provider.withFlag("test", value: true)
+ // State leaks to testScenario2
+ }
+}
+```
+
+### Use Named Test Scenarios
+
+```swift
+// ✅ Good - clear test intent
+func testPremiumUserWithHighUsage() {
+ let provider = MockContextProvider()
+ .withFlag("premium", value: true)
+ .withCounter("usage", value: 95)
+
+ // Test logic
+}
+
+// ❌ Avoid - unclear scenario
+func testSpec() {
+ let provider = MockContextProvider()
+ .withFlag("f1", value: true)
+ .withCounter("c1", value: 95)
+}
+```
+
+### Verify Request Counts When Relevant
+
+```swift
+// ✅ Good - verify lazy evaluation
+func testLazyEvaluation() {
+ let provider = MockContextProvider()
+ .withFlag("feature", value: false)
+
+ let spec = FeatureFlagSpec(flagKey: "feature")
+
+ // Should not request context until evaluation
+ XCTAssertEqual(provider.contextRequestCount, 0)
+
+ spec.isSatisfiedBy(provider.currentContext())
+
+ // Now should have requested context
+ XCTAssertEqual(provider.contextRequestCount, 1)
+}
+```
+
+## Performance Considerations
+
+- **Lightweight**: Mock providers have minimal overhead
+- **No Thread Safety**: Not thread-safe; use separate providers for concurrent tests
+- **Request Tracking**: Minimal overhead; safe to use in all tests
+- **Builder Pattern**: Each builder method creates a new context; efficient for testing
+
+## Topics
+
+### Creating Providers
+
+- ``init()``
+- ``init(context:)``
+- ``init(currentDate:launchDate:userData:counters:events:flags:)``
+
+### Context Management
+
+- ``mockContext``
+- ``setContext(_:)``
+- ``currentContext()``
+
+### Request Tracking
+
+- ``contextRequestCount``
+- ``onContextRequested``
+- ``resetRequestCount()``
+- ``verifyContextRequestCount(_:)``
+
+### Builder Methods
+
+- ``withCurrentDate(_:)``
+- ``withCounters(_:)``
+- ``withEvents(_:)``
+- ``withFlags(_:)``
+- ``withUserData(_:)``
+- ``withCounter(_:value:)``
+- ``withEvent(_:date:)``
+- ``withFlag(_:value:)``
+
+### Test Scenarios
+
+- ``launchDelayScenario(timeSinceLaunch:currentDate:)``
+- ``counterScenario(counterKey:counterValue:)``
+- ``cooldownScenario(eventKey:timeSinceEvent:currentDate:)``
+
+## See Also
+
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/PredicateSpec.md b/Sources/SpecificationCore/Documentation.docc/PredicateSpec.md
new file mode 100644
index 0000000..0e99415
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/PredicateSpec.md
@@ -0,0 +1,578 @@
+# ``SpecificationCore/PredicateSpec``
+
+A specification that accepts a closure for arbitrary logic.
+
+## Overview
+
+`PredicateSpec` provides maximum flexibility for custom business rules that don't fit into standard specification patterns. It allows you to create specifications from closures, KeyPath expressions, or use pre-built factory methods for common scenarios.
+
+### Key Benefits
+
+- **Flexible Creation**: Create specs from closures, predicates, or KeyPath expressions
+- **Type Safety**: Strongly-typed with generic context parameter
+- **Descriptive**: Optional description property for debugging and logging
+- **Composable**: Supports composition with other PredicateSpecs
+- **EvaluationContext Helpers**: Specialized methods for context-based specs
+
+### When to Use PredicateSpec
+
+Use `PredicateSpec` when you need to:
+- Create quick, inline specifications without defining new types
+- Prototype specifications before extracting to dedicated types
+- Implement simple one-off business rules
+- Use KeyPath-based property checks
+- Create context-aware predicates for feature flags and counters
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+struct User {
+ let age: Int
+ let email: String
+ let isActive: Bool
+}
+
+// Create from closure
+let adultSpec = PredicateSpec(description: "Is adult") { user in
+ user.age >= 18
+}
+
+// Create from KeyPath
+let activeSpec = PredicateSpec.keyPath(\.isActive, description: "Is active")
+
+// Create with property comparison
+let premiumSpec = PredicateSpec.keyPath(
+ \.subscriptionTier,
+ equals: "premium",
+ description: "Is premium user"
+)
+
+// Use like any specification
+if adultSpec.isSatisfiedBy(user) {
+ print("User is an adult")
+}
+```
+
+## Creating from Closures
+
+The most flexible way to create predicate specifications:
+
+```swift
+// Simple boolean predicate
+let emailValid = PredicateSpec(description: "Valid email") { user in
+ user.email.contains("@") && user.email.contains(".")
+}
+
+// Multi-line logic
+let eligibleForDiscount = PredicateSpec(
+ description: "Eligible for discount"
+) { user in
+ guard user.isActive else { return false }
+ let daysSinceRegistration = user.daysSinceRegistration
+ return daysSinceRegistration > 30 && user.purchaseCount < 5
+}
+
+// No description (optional)
+let quickCheck = PredicateSpec { $0.age >= 21 }
+```
+
+## KeyPath-Based Specifications
+
+Create specifications from Swift KeyPaths:
+
+### Boolean KeyPath
+
+```swift
+struct Account {
+ let isVerified: Bool
+ let isPremium: Bool
+}
+
+// Check boolean property
+let verifiedSpec = PredicateSpec.keyPath(\.isVerified)
+let premiumSpec = PredicateSpec.keyPath(\.isPremium, description: "Premium account")
+
+let account = Account(isVerified: true, isPremium: false)
+verifiedSpec.isSatisfiedBy(account) // true
+```
+
+### Equality Checks
+
+```swift
+struct Order {
+ let status: String
+ let priority: Int
+}
+
+// Check for specific value
+let completedSpec = PredicateSpec.keyPath(
+ \.status,
+ equals: "completed"
+)
+
+let highPrioritySpec = PredicateSpec.keyPath(
+ \.priority,
+ equals: 1,
+ description: "High priority"
+)
+
+let order = Order(status: "completed", priority: 1)
+completedSpec.isSatisfiedBy(order) // true
+```
+
+### Comparison Operations
+
+```swift
+struct Product {
+ let price: Decimal
+ let stock: Int
+ let rating: Double
+}
+
+// Greater than
+let expensiveSpec = PredicateSpec.keyPath(
+ \.price,
+ greaterThan: 100.0
+)
+
+// Less than
+let lowStockSpec = PredicateSpec.keyPath(
+ \.stock,
+ lessThan: 10
+)
+
+// Range check
+let ratedSpec = PredicateSpec.keyPath(
+ \.rating,
+ in: 4.0...5.0,
+ description: "Highly rated"
+)
+```
+
+## EvaluationContext Specifications
+
+Specialized factory methods for working with ``EvaluationContext``:
+
+### Flag Checking
+
+```swift
+// Check if flag is true
+let premiumEnabled = PredicateSpec.flag("premium_features")
+
+// Check for specific value
+let betaDisabled = PredicateSpec.flag("beta_mode", equals: false)
+
+// With description
+let analyticsSpec = PredicateSpec.flag(
+ "analytics_enabled",
+ equals: true,
+ description: "Analytics enabled"
+)
+
+let context = EvaluationContext(flags: ["premium_features": true])
+premiumEnabled.isSatisfiedBy(context) // true
+```
+
+### Counter Checking
+
+```swift
+// Check counter value with comparison
+let withinLimit = PredicateSpec.counter(
+ "api_calls",
+ .lessThan,
+ 100
+)
+
+let exactCount = PredicateSpec.counter(
+ "login_attempts",
+ .equal,
+ 3,
+ description: "Exactly 3 attempts"
+)
+
+let highUsage = PredicateSpec.counter(
+ "daily_requests",
+ .greaterThanOrEqual,
+ 1000
+)
+
+// Available comparisons: .lessThan, .lessThanOrEqual, .equal,
+// .greaterThanOrEqual, .greaterThan, .notEqual
+```
+
+### Event Checking
+
+```swift
+// Check if event exists
+let hasLoggedIn = PredicateSpec.eventExists("last_login")
+
+let hasCompletedTutorial = PredicateSpec.eventExists(
+ "tutorial_completed",
+ description: "Tutorial completed"
+)
+
+let context = EvaluationContext(
+ events: ["last_login": Date()]
+)
+hasLoggedIn.isSatisfiedBy(context) // true
+```
+
+### Time-Based Specifications
+
+```swift
+// Check time since launch
+let runningSufficiently = PredicateSpec.timeSinceLaunch(
+ greaterThan: 60 // 1 minute
+)
+
+// Check current hour
+let businessHours = PredicateSpec.currentHour(in: 9...17)
+
+let lateNight = PredicateSpec.currentHour(
+ in: 22...6, // Wraps around midnight
+ description: "Late night hours"
+)
+
+// Weekday/weekend checks
+let isWeekday = PredicateSpec.isWeekday()
+let isWeekend = PredicateSpec.isWeekend(description: "Weekend")
+```
+
+## Constant Specifications
+
+Pre-built specifications for edge cases:
+
+```swift
+// Always returns true
+let alwaysTrue = PredicateSpec.alwaysTrue()
+
+// Always returns false
+let alwaysFalse = PredicateSpec.alwaysFalse()
+
+// Useful for conditional logic
+let spec = isMaintenanceMode
+ ? PredicateSpec.alwaysFalse()
+ : ActualEligibilitySpec()
+```
+
+## Composition
+
+Combine PredicateSpecs with logical operators:
+
+### AND Composition
+
+```swift
+let adult = PredicateSpec { $0.age >= 18 }
+let active = PredicateSpec { $0.isActive }
+
+// Combine with AND
+let eligible = adult.and(active)
+
+// Description is combined
+print(eligible.description) // "Is adult AND Is active"
+```
+
+### OR Composition
+
+```swift
+let premium = PredicateSpec { $0.tier == "premium" }
+let trial = PredicateSpec { $0.tier == "trial" }
+
+// Combine with OR
+let hasAccess = premium.or(trial)
+```
+
+### NOT Composition
+
+```swift
+let banned = PredicateSpec { $0.isBanned }
+
+// Negate
+let notBanned = banned.not()
+
+print(notBanned.description) // "NOT (Is banned)"
+```
+
+### Complex Composition
+
+```swift
+let adultSpec = PredicateSpec(description: "Adult") { $0.age >= 18 }
+let activeSpec = PredicateSpec(description: "Active") { $0.isActive }
+let bannedSpec = PredicateSpec(description: "Banned") { $0.isBanned }
+
+// (Adult AND Active) AND NOT Banned
+let eligible = adultSpec
+ .and(activeSpec)
+ .and(bannedSpec.not())
+```
+
+## Contramap Transformation
+
+Transform the input type of a predicate:
+
+```swift
+struct User {
+ let profile: UserProfile
+}
+
+struct UserProfile {
+ let age: Int
+}
+
+// Spec for UserProfile
+let adultProfileSpec = PredicateSpec { $0.age >= 18 }
+
+// Transform to work with User
+let adultUserSpec = adultProfileSpec.contramap { (user: User) in
+ user.profile
+}
+
+let user = User(profile: UserProfile(age: 25))
+adultUserSpec.isSatisfiedBy(user) // true
+```
+
+## Collection Extensions
+
+Create specifications from collections of specifications:
+
+```swift
+let validations: [PredicateSpec] = [
+ PredicateSpec { $0.email.contains("@") },
+ PredicateSpec { $0.age >= 18 },
+ PredicateSpec { $0.isActive }
+]
+
+// All must be satisfied (AND)
+let allValid = validations.allSatisfiedPredicate()
+
+// Any can be satisfied (OR)
+let anyValid = validations.anySatisfiedPredicate()
+```
+
+## Debugging with Descriptions
+
+Use descriptions for logging and debugging:
+
+```swift
+let spec = PredicateSpec(description: "Premium user check") { user in
+ user.subscriptionTier == "premium" && user.isActive
+}
+
+// Access description
+print("Evaluating: \(spec.description ?? "unnamed spec")")
+
+// Useful in logs
+func evaluate(user: User, with spec: PredicateSpec) -> Bool {
+ let result = spec.isSatisfiedBy(user)
+ print("[\(spec.description ?? "spec")] = \(result)")
+ return result
+}
+```
+
+## Real-World Examples
+
+### Form Validation
+
+```swift
+struct RegistrationForm {
+ let email: String
+ let password: String
+ let age: Int
+ let agreedToTerms: Bool
+}
+
+let validEmail = PredicateSpec(
+ description: "Valid email"
+) { form in
+ let emailRegex = "[A-Z0-9a-z._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}"
+ return NSPredicate(format: "SELF MATCHES %@", emailRegex)
+ .evaluate(with: form.email)
+}
+
+let strongPassword = PredicateSpec(
+ description: "Strong password"
+) { form in
+ form.password.count >= 8 &&
+ form.password.rangeOfCharacter(from: .uppercaseLetters) != nil &&
+ form.password.rangeOfCharacter(from: .decimalDigits) != nil
+}
+
+let legalAge = PredicateSpec.keyPath(
+ \RegistrationForm.age,
+ greaterThanOrEqual: 18,
+ description: "Legal age"
+)
+
+let termsAccepted = PredicateSpec.keyPath(
+ \.agreedToTerms,
+ description: "Terms accepted"
+)
+
+// Combine all validations
+let formValid = validEmail
+ .and(strongPassword)
+ .and(legalAge)
+ .and(termsAccepted)
+```
+
+### Feature Access Control
+
+```swift
+// Context-based feature access
+let canAccessPremiumFeatures = PredicateSpec(
+ description: "Premium feature access"
+) { context in
+ let isPremium = context.flag(for: "is_premium")
+ let withinLimit = context.counter(for: "monthly_usage") < 1000
+ let notOnCooldown = context.timeSinceEvent("last_feature_use")
+ .map { $0 > 3600 } ?? true
+
+ return isPremium && withinLimit && notOnCooldown
+}
+```
+
+### Business Hours Check
+
+```swift
+let isDuringBusinessHours = PredicateSpec(
+ description: "Business hours"
+) { context in
+ let calendar = context.calendar
+ let components = calendar.dateComponents(
+ [.hour, .weekday],
+ from: context.currentDate
+ )
+
+ guard let hour = components.hour,
+ let weekday = components.weekday else {
+ return false
+ }
+
+ let isWeekday = (2...6).contains(weekday) // Mon-Fri
+ let isBusinessHours = (9...17).contains(hour) // 9 AM - 5 PM
+
+ return isWeekday && isBusinessHours
+}
+```
+
+## Best Practices
+
+### Provide Descriptions
+
+```swift
+// ✅ Good - descriptive for debugging
+let spec = PredicateSpec(description: "Active premium user") { user in
+ user.isActive && user.tier == "premium"
+}
+
+// ❌ Less useful - no description
+let spec = PredicateSpec { user in
+ user.isActive && user.tier == "premium"
+}
+```
+
+### Keep Predicates Focused
+
+```swift
+// ✅ Good - single responsibility
+let adultSpec = PredicateSpec(description: "Adult") { $0.age >= 18 }
+let activeSpec = PredicateSpec(description: "Active") { $0.isActive }
+let eligible = adultSpec.and(activeSpec)
+
+// ❌ Avoid - mixed concerns in one predicate
+let spec = PredicateSpec { user in
+ user.age >= 18 && user.isActive && user.email.contains("@")
+}
+```
+
+### Use KeyPath Methods When Possible
+
+```swift
+// ✅ Good - concise with KeyPath
+let activeSpec = PredicateSpec.keyPath(\.isActive)
+
+// ❌ Verbose - unnecessary closure
+let activeSpec = PredicateSpec { user in
+ user.isActive
+}
+```
+
+### Extract Complex Logic
+
+```swift
+// ✅ Good - extract to named function
+func isEligibleForRefund(_ order: Order) -> Bool {
+ let daysSincePurchase = Date().timeIntervalSince(order.purchaseDate) / 86400
+ return daysSincePurchase <= 30 && !order.isRefunded
+}
+
+let refundEligible = PredicateSpec(
+ description: "Refund eligible",
+ isEligibleForRefund
+)
+
+// ❌ Harder to read - complex inline logic
+let refundEligible = PredicateSpec { order in
+ let daysSincePurchase = Date().timeIntervalSince(order.purchaseDate) / 86400
+ return daysSincePurchase <= 30 && !order.isRefunded
+}
+```
+
+## Performance Considerations
+
+- **Closure Overhead**: Minimal overhead; closures are stored and called directly
+- **KeyPath Performance**: KeyPath access is optimized by Swift runtime
+- **Description Storage**: Optional string has minimal memory impact
+- **Composition**: Each composition creates a new PredicateSpec; efficient for short chains
+- **Collection Methods**: `allSatisfiedPredicate()` short-circuits on first failure
+
+## Topics
+
+### Creating Specifications
+
+- ``init(description:_:)``
+
+### Constant Specifications
+
+- ``alwaysTrue()``
+- ``alwaysFalse()``
+
+### KeyPath-Based Creation
+
+- ``keyPath(_:description:)`` (Boolean)
+- ``keyPath(_:equals:description:)`` (Equatable)
+- ``keyPath(_:greaterThan:description:)``
+- ``keyPath(_:lessThan:description:)``
+- ``keyPath(_:in:description:)`` (Range)
+
+### EvaluationContext Helpers
+
+- ``flag(_:equals:description:)``
+- ``counter(_:_:_:description:)``
+- ``eventExists(_:description:)``
+- ``timeSinceLaunch(greaterThan:description:)``
+- ``currentHour(in:description:)``
+- ``isWeekday(description:)``
+- ``isWeekend(description:)``
+
+### Composition
+
+- ``and(_:)``
+- ``or(_:)``
+- ``not()``
+- ``contramap(_:)``
+
+### Properties
+
+- ``description``
+
+### Supporting Types
+
+- ``CounterComparison``
+
+## See Also
+
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/Satisfies.md b/Sources/SpecificationCore/Documentation.docc/Satisfies.md
new file mode 100644
index 0000000..54fe36c
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Satisfies.md
@@ -0,0 +1,623 @@
+# ``SpecificationCore/Satisfies``
+
+A property wrapper that provides declarative specification evaluation with boolean results.
+
+## Overview
+
+`@Satisfies` enables clean, readable specification usage by automatically handling context retrieval and specification evaluation. It transforms complex specification evaluation into simple boolean properties, making your code more expressive and maintainable.
+
+### Key Benefits
+
+- **Declarative Syntax**: Convert specification evaluation into readable property declarations
+- **Automatic Context**: Handles context provider integration automatically
+- **Multiple Initialization Patterns**: Supports specifications, predicates, and builders
+- **Async Support**: Optional async evaluation through projected value
+- **Type-Safe**: Compile-time safety for context and specification types
+- **Composable**: Works with all specification types and operators
+
+### When to Use @Satisfies
+
+Use `@Satisfies` when you need to:
+- Convert specification evaluation into properties
+- Simplify boolean condition checking
+- Create declarative feature flags or eligibility checks
+- Automatically manage context provider access
+- Build reactive UIs based on specification results
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+// Simple feature flag check
+@Satisfies(using: FeatureFlagSpec(flagKey: "new_ui"))
+var isNewUIEnabled: Bool
+
+// Usage
+if isNewUIEnabled {
+ showNewUI()
+} else {
+ showLegacyUI()
+}
+```
+
+## Creating @Satisfies
+
+### With Specification Instances
+
+```swift
+// Using a specification instance
+@Satisfies(using: MaxCountSpec(counterKey: "api_calls", maximumCount: 100))
+var canMakeAPICall: Bool
+
+// Using custom provider
+@Satisfies(provider: customProvider, using: PremiumUserSpec())
+var isPremiumUser: Bool
+```
+
+### With Predicates
+
+```swift
+// Simple predicate
+@Satisfies(predicate: { context in
+ context.counter(for: "login_attempts") < 5
+})
+var canAttemptLogin: Bool
+
+// With custom provider
+@Satisfies(provider: myProvider, predicate: { context in
+ context.flag(for: "beta_access") && context.counter(for: "sessions") > 10
+})
+var hasBetaAccess: Bool
+```
+
+### With Manual Context
+
+```swift
+// Provide context directly
+let myContext = EvaluationContext(currentDate: Date())
+
+@Satisfies(context: myContext, using: DateRangeSpec(start: startDate, end: endDate))
+var isInDateRange: Bool
+```
+
+### With Specification Types
+
+```swift
+// For specifications conforming to ExpressibleByNilLiteral
+@Satisfies(using: FeatureFlagSpec.self)
+var isFeatureEnabled: Bool
+```
+
+## How It Works
+
+The property wrapper evaluates the specification each time the property is accessed:
+
+```swift
+@Satisfies(using: MaxCountSpec(counterKey: "attempts", maximumCount: 3))
+var canRetry: Bool
+
+// Each access re-evaluates:
+if canRetry { // Evaluates specification
+ attemptOperation()
+ provider.incrementCounter("attempts")
+}
+
+if canRetry { // Re-evaluates with updated context
+ attemptAgain()
+}
+```
+
+## Usage Examples
+
+### Feature Flag Management
+
+```swift
+@Satisfies(using: FeatureFlagSpec(flagKey: "premium_features"))
+var showPremiumFeatures: Bool
+
+@Satisfies(using: FeatureFlagSpec(flagKey: "experimental_ui"))
+var useExperimentalUI: Bool
+
+@Satisfies(using: FeatureFlagSpec(flagKey: "analytics_enabled"))
+var shouldTrackAnalytics: Bool
+
+func setupApp() {
+ if showPremiumFeatures {
+ enablePremiumContent()
+ }
+
+ if useExperimentalUI {
+ loadExperimentalComponents()
+ }
+
+ if shouldTrackAnalytics {
+ startAnalyticsTracking()
+ }
+}
+```
+
+### User Eligibility Checks
+
+```swift
+@Satisfies(using: TimeSinceEventSpec(eventKey: "user_registered", days: 30))
+var isLoyalUser: Bool
+
+@Satisfies(using: MaxCountSpec(counterKey: "purchases", maximumCount: 0).not())
+var hasMadePurchases: Bool
+
+@Satisfies(predicate: { context in
+ context.flag(for: "email_verified") &&
+ context.counter(for: "profile_completeness") >= 80
+})
+var hasCompleteProfile: Bool
+
+func checkRewardEligibility() {
+ if isLoyalUser && hasMadePurchases && hasCompleteProfile {
+ offerLoyaltyReward()
+ }
+}
+```
+
+### Rate Limiting
+
+```swift
+@Satisfies(using: MaxCountSpec.dailyLimit("api_requests", limit: 1000))
+var canMakeRequest: Bool
+
+@Satisfies(using: CooldownIntervalSpec.hourly("notification_sent"))
+var canSendNotification: Bool
+
+func performAPICall() async throws {
+ guard canMakeRequest else {
+ throw APIError.rateLimitExceeded
+ }
+
+ let response = try await makeRequest()
+ DefaultContextProvider.shared.incrementCounter("api_requests")
+ return response
+}
+```
+
+### Complex Conditions
+
+```swift
+// Combine multiple specifications
+@Satisfies(predicate: { context in
+ // Premium user OR trial user with remaining days
+ let isPremium = context.flag(for: "premium_subscription")
+ let isTrialActive = context.flag(for: "trial_active")
+ let trialDaysRemaining = context.counter(for: "trial_days_remaining")
+
+ return isPremium || (isTrialActive && trialDaysRemaining > 0)
+})
+var hasProAccess: Bool
+```
+
+## Builder Pattern
+
+Create complex specifications using the builder API:
+
+```swift
+@Satisfies(build: { builder in
+ builder
+ .with(FeatureFlagSpec(flagKey: "feature_enabled"))
+ .with { context in context.counter(for: "sessions") >= 5 }
+ .with(TimeSinceEventSpec(eventKey: "first_launch", days: 7))
+ .buildAll() // Requires ALL conditions
+})
+var isEligibleForAdvancedFeatures: Bool
+
+@Satisfies(build: { builder in
+ builder
+ .with(PremiumUserSpec())
+ .with(BetaUserSpec())
+ .buildAny() // Requires ANY condition
+})
+var hasSpecialAccess: Bool
+```
+
+## Convenience Initializers
+
+### Time-Based Conditions
+
+```swift
+// Time since app launch
+@Satisfies(Satisfies.timeSinceLaunch(minimumSeconds: 300))
+var hasBeenRunningLongEnough: Bool
+
+// Custom cooldown
+@Satisfies(Satisfies.cooldown("last_prompt", minimumInterval: 3600))
+var canShowPrompt: Bool
+```
+
+### Counter-Based Conditions
+
+```swift
+@Satisfies(Satisfies.counter("login_attempts", lessThan: 5))
+var canAttemptLogin: Bool
+
+@Satisfies(Satisfies.counter("page_views", lessThan: 10))
+var isWithinFreeLimit: Bool
+```
+
+### Flag-Based Conditions
+
+```swift
+@Satisfies(Satisfies.flag("dark_mode_enabled"))
+var isDarkModeEnabled: Bool
+
+@Satisfies(Satisfies.flag("notifications_allowed", equals: true))
+var canSendNotifications: Bool
+```
+
+## Async Evaluation
+
+Access async evaluation through the projected value:
+
+```swift
+@Satisfies(using: AsyncRemoteConfigSpec(key: "feature_gate"))
+var isRemoteFeatureEnabled: Bool
+
+func checkFeature() async {
+ do {
+ let enabled = try await $isRemoteFeatureEnabled.evaluateAsync()
+ if enabled {
+ activateFeature()
+ }
+ } catch {
+ handleError(error)
+ }
+}
+```
+
+## Real-World Examples
+
+### App Launch Flow
+
+```swift
+class AppCoordinator {
+ @Satisfies(using: TimeSinceEventSpec(eventKey: "first_launch", hours: 0).not())
+ var isFirstLaunch: Bool
+
+ @Satisfies(using: MaxCountSpec.onlyOnce("onboarding_completed").not())
+ var needsOnboarding: Bool
+
+ @Satisfies(predicate: { context in
+ context.flag(for: "user_logged_in")
+ })
+ var isUserLoggedIn: Bool
+
+ func determineInitialRoute() -> AppRoute {
+ if isFirstLaunch {
+ return .welcome
+ } else if needsOnboarding {
+ return .onboarding
+ } else if !isUserLoggedIn {
+ return .login
+ } else {
+ return .home
+ }
+ }
+}
+```
+
+### Feature Gate System
+
+```swift
+struct FeatureGate {
+ @Satisfies(using: FeatureFlagSpec(flagKey: "experimental_ai"))
+ var hasAIFeatures: Bool
+
+ @Satisfies(using: FeatureFlagSpec(flagKey: "beta_testing"))
+ var isBetaTester: Bool
+
+ @Satisfies(predicate: { context in
+ context.flag(for: "premium_subscription") ||
+ context.flag(for: "lifetime_access")
+ })
+ var hasPremiumAccess: Bool
+
+ func canAccessFeature(_ feature: Feature) -> Bool {
+ switch feature {
+ case .aiGeneration:
+ return hasAIFeatures && hasPremiumAccess
+ case .advancedAnalytics:
+ return hasPremiumAccess
+ case .experimentalFeatures:
+ return isBetaTester
+ case .basicFeatures:
+ return true
+ }
+ }
+}
+```
+
+### Rate Limit Manager
+
+```swift
+class RateLimitManager {
+ @Satisfies(using: MaxCountSpec.dailyLimit("api_calls", limit: 10000))
+ var withinDailyLimit: Bool
+
+ @Satisfies(using: MaxCountSpec(counterKey: "api_calls_this_hour", maximumCount: 1000))
+ var withinHourlyLimit: Bool
+
+ @Satisfies(using: CooldownIntervalSpec(eventKey: "last_burst", seconds: 1))
+ var notInBurstCooldown: Bool
+
+ func canMakeRequest(type: RequestType) -> Bool {
+ guard withinDailyLimit else {
+ return false
+ }
+
+ switch type {
+ case .standard:
+ return withinHourlyLimit
+ case .burst:
+ return withinHourlyLimit && notInBurstCooldown
+ case .priority:
+ return true // Priority requests bypass rate limits
+ }
+ }
+
+ func recordRequest(type: RequestType) {
+ let provider = DefaultContextProvider.shared
+ provider.incrementCounter("api_calls")
+ provider.incrementCounter("api_calls_this_hour")
+
+ if type == .burst {
+ provider.recordEvent("last_burst")
+ }
+ }
+}
+```
+
+### Subscription Management
+
+```swift
+class SubscriptionManager {
+ @Satisfies(predicate: { context in
+ context.flag(for: "subscription_active")
+ })
+ var hasActiveSubscription: Bool
+
+ @Satisfies(using: DateComparisonSpec(
+ eventKey: "subscription_expired",
+ comparison: .before,
+ date: Date().addingTimeInterval(3 * 86400) // 3 day grace
+ ))
+ var isInGracePeriod: Bool
+
+ @Satisfies(using: TimeSinceEventSpec(eventKey: "trial_started", days: 14).not())
+ var isTrialActive: Bool
+
+ func getAccessLevel() -> AccessLevel {
+ if hasActiveSubscription {
+ return .premium
+ } else if isInGracePeriod {
+ return .gracePeriod
+ } else if isTrialActive {
+ return .trial
+ } else {
+ return .free
+ }
+ }
+
+ func canAccessPremiumContent() -> Bool {
+ return hasActiveSubscription || isInGracePeriod || isTrialActive
+ }
+}
+```
+
+## Composition with Specifications
+
+Use specification operators for complex logic:
+
+```swift
+// Create composed specifications
+let premiumSpec = FeatureFlagSpec(flagKey: "premium")
+let trialSpec = FeatureFlagSpec(flagKey: "trial_active")
+let accessSpec = premiumSpec.or(trialSpec)
+
+@Satisfies(using: accessSpec)
+var hasProAccess: Bool
+
+// Negation
+let blockedSpec = FeatureFlagSpec(flagKey: "account_blocked")
+@Satisfies(using: blockedSpec.not())
+var isNotBlocked: Bool
+
+// Complex composition
+let eligibilitySpec = PremiumUserSpec()
+ .and(EmailVerifiedSpec())
+ .and(MaxCountSpec(counterKey: "violations", maximumCount: 1))
+
+@Satisfies(using: eligibilitySpec)
+var isEligibleForRewards: Bool
+```
+
+## Testing
+
+Test property wrapper usage with ``MockContextProvider``:
+
+```swift
+func testFeatureFlag() {
+ // Setup mock context
+ let provider = MockContextProvider()
+ .withFlag("premium_features", value: true)
+
+ // Create specification that uses the provider
+ @Satisfies(provider: provider, using: FeatureFlagSpec(flagKey: "premium_features"))
+ var hasPremium: Bool
+
+ // Test evaluation
+ XCTAssertTrue(hasPremium)
+
+ // Update context
+ provider.setFlag("premium_features", to: false)
+
+ // Re-evaluation reflects new context
+ XCTAssertFalse(hasPremium)
+}
+
+func testRateLimit() {
+ let provider = MockContextProvider()
+ .withCounter("api_calls", value: 99)
+
+ @Satisfies(
+ provider: provider,
+ using: MaxCountSpec(counterKey: "api_calls", maximumCount: 100)
+ )
+ var canMakeCall: Bool
+
+ // Under limit
+ XCTAssertTrue(canMakeCall)
+
+ // Reach limit
+ provider.setCounter("api_calls", to: 100)
+ XCTAssertFalse(canMakeCall)
+}
+
+func testAsyncEvaluation() async throws {
+ let provider = MockContextProvider()
+ .withFlag("remote_feature", value: true)
+
+ @Satisfies(provider: provider, using: FeatureFlagSpec(flagKey: "remote_feature"))
+ var isEnabled: Bool
+
+ let result = try await $isEnabled.evaluateAsync()
+ XCTAssertTrue(result)
+}
+```
+
+## Best Practices
+
+### Use Descriptive Property Names
+
+```swift
+// ✅ Good - clear intent
+@Satisfies(using: PremiumUserSpec())
+var hasPremiumAccess: Bool
+
+@Satisfies(using: MaxCountSpec.dailyLimit("exports", limit: 10))
+var canExportToday: Bool
+
+// ❌ Avoid - unclear purpose
+@Satisfies(using: PremiumUserSpec())
+var spec1: Bool
+
+@Satisfies(using: MaxCountSpec.dailyLimit("exports", limit: 10))
+var check: Bool
+```
+
+### Choose Appropriate Initialization
+
+```swift
+// ✅ Good - simple specification
+@Satisfies(using: FeatureFlagSpec(flagKey: "new_feature"))
+var isFeatureEnabled: Bool
+
+// ✅ Good - simple predicate for inline logic
+@Satisfies(predicate: { context in
+ context.counter(for: "score") > 100
+})
+var hasHighScore: Bool
+
+// ✅ Good - complex composition with builder
+@Satisfies(build: { builder in
+ builder
+ .with(Spec1())
+ .with(Spec2())
+ .buildAll()
+})
+var meetsComplexCriteria: Bool
+```
+
+### Consider Re-Evaluation Cost
+
+```swift
+// ✅ Good - lightweight evaluation
+@Satisfies(using: FeatureFlagSpec(flagKey: "simple_flag"))
+var isEnabled: Bool
+
+// ⚠️ Consider caching - expensive evaluation
+@Satisfies(predicate: { context in
+ // Expensive computation on each access
+ performComplexCalculation(context)
+})
+var expensiveCheck: Bool
+
+// ✅ Better - cache or use alternative approach
+let cachedResult = performComplexCalculation(context)
+@Satisfies({ _ in cachedResult })
+var cachedCheck: Bool
+```
+
+### Handle Provider Lifecycle
+
+```swift
+// ✅ Good - use shared provider for simple cases
+@Satisfies(using: FeatureFlagSpec(flagKey: "feature"))
+var isEnabled: Bool
+
+// ✅ Good - custom provider for specific needs
+let scopedProvider = DefaultContextProvider()
+@Satisfies(provider: scopedProvider, using: MySpec())
+var isSatisfied: Bool
+
+// ✅ Good - manual context for testing or special cases
+@Satisfies(context: testContext, using: MySpec())
+var testResult: Bool
+```
+
+## Performance Considerations
+
+- **Evaluation on Access**: Specification is evaluated each time the property is accessed
+- **Context Fetching**: Context is fetched from provider on each evaluation
+- **No Caching**: No automatic caching of results; re-evaluates every time
+- **Lightweight Specs**: Use simple specifications for properties accessed frequently
+- **Async Overhead**: Async evaluation via projected value has async context fetching overhead
+- **Provider Cost**: Context provider performance affects property access performance
+
+Consider using cached variants or manual caching for expensive evaluations:
+
+```swift
+// For expensive specifications accessed frequently
+class ViewModel {
+ private var cachedValue: Bool?
+ private let spec = ExpensiveSpec()
+
+ var isExpensiveConditionMet: Bool {
+ if let cached = cachedValue {
+ return cached
+ }
+ let result = spec.isSatisfiedBy(context)
+ cachedValue = result
+ return result
+ }
+
+ func invalidateCache() {
+ cachedValue = nil
+ }
+}
+```
+
+## Topics
+
+### Property Values
+
+- ``wrappedValue``
+- ``projectedValue``
+
+### Async Support
+
+- ``evaluateAsync()``
+
+## See Also
+
+-
+-
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/Specification.md b/Sources/SpecificationCore/Documentation.docc/Specification.md
new file mode 100644
index 0000000..88c5f7b
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Specification.md
@@ -0,0 +1,298 @@
+# ``SpecificationCore/Specification``
+
+A protocol that evaluates whether a context satisfies certain conditions.
+
+## Overview
+
+The `Specification` protocol is the foundation of SpecificationCore, implementing the Specification Pattern to encapsulate business rules and conditions in a composable, testable manner. Specifications allow you to define complex business logic through small, focused components that can be combined using logical operators.
+
+### Key Benefits
+
+- **Composability**: Combine specifications using `.and()`, `.or()`, and `.not()` operators
+- **Reusability**: Define specifications once, use them throughout your application
+- **Testability**: Small, focused specifications are easy to unit test
+- **Maintainability**: Business rules are explicit and self-documenting
+- **Type Safety**: Generic associated type ensures compile-time correctness
+
+### When to Use Specifications
+
+Use the Specification pattern when you need to:
+- Define reusable business rules that can be combined
+- Separate business logic from domain objects
+- Create flexible validation and filtering criteria
+- Build complex eligibility or authorization checks
+- Implement feature flags or A/B testing logic
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+struct User {
+ let age: Int
+ let isActive: Bool
+ let subscriptionTier: String
+}
+
+// Define a simple specification
+struct AdultUserSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.age >= 18
+ }
+}
+
+// Use the specification
+let spec = AdultUserSpec()
+let user = User(age: 25, isActive: true, subscriptionTier: "premium")
+
+if spec.isSatisfiedBy(user) {
+ print("User is an adult")
+}
+```
+
+## Composing Specifications
+
+The real power of specifications comes from composition. Combine simple specifications to create complex business rules:
+
+```swift
+struct ActiveUserSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.isActive
+ }
+}
+
+struct PremiumUserSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.subscriptionTier == "premium"
+ }
+}
+
+// Combine specifications
+let eligibleSpec = AdultUserSpec()
+ .and(ActiveUserSpec())
+ .and(PremiumUserSpec())
+
+if eligibleSpec.isSatisfiedBy(user) {
+ print("User is eligible for premium features")
+}
+```
+
+## Using Logical Operators
+
+SpecificationCore provides three logical operators for composition:
+
+### AND Operator
+
+Creates a specification satisfied when both specifications are satisfied:
+
+```swift
+let adultAndActive = AdultUserSpec().and(ActiveUserSpec())
+// Satisfied only when user is BOTH adult AND active
+```
+
+### OR Operator
+
+Creates a specification satisfied when either specification is satisfied:
+
+```swift
+struct TrialUserSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.subscriptionTier == "trial"
+ }
+}
+
+let hasAccessSpec = PremiumUserSpec().or(TrialUserSpec())
+// Satisfied when user is premium OR trial
+```
+
+### NOT Operator
+
+Creates a specification that inverts the result:
+
+```swift
+let inactiveUserSpec = ActiveUserSpec().not()
+// Satisfied when user is NOT active
+```
+
+## Operator Syntax
+
+For more concise composition, use the operator overloads:
+
+```swift
+// Using method syntax
+let spec1 = AdultUserSpec().and(ActiveUserSpec()).or(PremiumUserSpec())
+
+// Using operator syntax
+let spec2 = AdultUserSpec() && ActiveUserSpec() || PremiumUserSpec()
+
+// Using NOT operator
+let notAdult = !AdultUserSpec()
+```
+
+## Creating Custom Specifications
+
+Implement the `Specification` protocol with a single method:
+
+```swift
+struct MinimumBalanceSpec: Specification {
+ let minimumAmount: Decimal
+
+ func isSatisfiedBy(_ account: BankAccount) -> Bool {
+ account.balance >= minimumAmount
+ }
+}
+
+// Use with different minimum values
+let standardSpec = MinimumBalanceSpec(minimumAmount: 100)
+let premiumSpec = MinimumBalanceSpec(minimumAmount: 1000)
+```
+
+## Using with Property Wrappers
+
+Combine specifications with property wrappers for declarative evaluation:
+
+```swift
+import SpecificationCore
+
+struct UserViewModel {
+ let user: User
+
+ @Satisfies(using: AdultUserSpec().and(ActiveUserSpec()))
+ var canAccessContent: Bool
+
+ init(user: User) {
+ self.user = user
+ _canAccessContent = Satisfies(
+ using: AdultUserSpec().and(ActiveUserSpec()),
+ with: user
+ )
+ }
+}
+
+let viewModel = UserViewModel(user: user)
+if viewModel.canAccessContent {
+ // Show restricted content
+}
+```
+
+## Best Practices
+
+### Keep Specifications Focused
+
+Each specification should test one business rule:
+
+```swift
+// ✅ Good - focused specifications
+struct IsAdultSpec: Specification { /* ... */ }
+struct HasActiveSubscriptionSpec: Specification { /* ... */ }
+let eligibleSpec = IsAdultSpec().and(HasActiveSubscriptionSpec())
+
+// ❌ Avoid - mixed concerns
+struct IsEligibleSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.age >= 18 && user.subscription.isActive && user.emailVerified
+ }
+}
+```
+
+### Make Specifications Stateless
+
+Specifications should be pure functions without side effects:
+
+```swift
+// ✅ Good - stateless
+struct AgeSpec: Specification {
+ let minimumAge: Int
+
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.age >= minimumAge
+ }
+}
+
+// ❌ Avoid - stateful with side effects
+struct CountingSpec: Specification {
+ var callCount = 0 // Mutable state
+
+ mutating func isSatisfiedBy(_ user: User) -> Bool {
+ callCount += 1 // Side effect
+ return user.isActive
+ }
+}
+```
+
+### Use Type-Safe Contexts
+
+Leverage Swift's type system for compile-time safety:
+
+```swift
+// Define specific context types
+struct OrderContext {
+ let totalAmount: Decimal
+ let itemCount: Int
+ let customerId: String
+}
+
+struct MinimumOrderSpec: Specification {
+ let minimumAmount: Decimal
+
+ func isSatisfiedBy(_ order: OrderContext) -> Bool {
+ order.totalAmount >= minimumAmount
+ }
+}
+```
+
+## Performance Considerations
+
+- **Lightweight Evaluation**: Keep `isSatisfiedBy(_:)` implementations fast, as they may be called frequently
+- **Short-Circuit Evaluation**: AND and OR operations short-circuit for efficiency
+- **Thread Safety**: Ensure specifications are thread-safe when used in concurrent contexts
+- **Avoid Heavy Computation**: For expensive operations, consider caching or using ``AsyncSpecification``
+
+## Topics
+
+### Essential Protocol
+
+- ``isSatisfiedBy(_:)``
+
+### Logical Composition
+
+- ``and(_:)``
+- ``or(_:)``
+- ``not()``
+
+### Composite Types
+
+- ``AndSpecification``
+- ``OrSpecification``
+- ``NotSpecification``
+
+### Type Erasure
+
+- ``AnySpecification``
+
+### Related Protocols
+
+- ``DecisionSpec``
+- ``AsyncSpecification``
+
+### Built-in Specifications
+
+- ``PredicateSpec``
+- ``MaxCountSpec``
+- ``CooldownIntervalSpec``
+- ``TimeSinceEventSpec``
+- ``DateRangeSpec``
+- ``DateComparisonSpec``
+
+### Property Wrappers
+
+- ``Satisfies``
+- ``Decides``
+- ``Maybe``
+
+## See Also
+
+-
+-
+-
+- ``PredicateSpec``
diff --git a/Sources/SpecificationCore/Documentation.docc/SpecificationCore.md b/Sources/SpecificationCore/Documentation.docc/SpecificationCore.md
new file mode 100644
index 0000000..0dd3590
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/SpecificationCore.md
@@ -0,0 +1,142 @@
+# ``SpecificationCore``
+
+Platform-independent core for building specification-based business logic in Swift.
+
+## Overview
+
+**SpecificationCore** provides the foundational protocols, specifications, property wrappers, and macros for implementing the Specification Pattern in Swift. It's designed to be platform-independent and works across iOS, macOS, tvOS, watchOS, and Linux.
+
+### What is SpecificationCore?
+
+SpecificationCore is the core library extracted from SpecificationKit that contains:
+- Core protocols (`Specification`, `DecisionSpec`, `AsyncSpecification`)
+- Context infrastructure (`EvaluationContext`, `DefaultContextProvider`)
+- Basic specifications (`PredicateSpec`, `MaxCountSpec`, `FirstMatchSpec`, etc.)
+- Property wrappers (`@Satisfies`, `@Decides`, `@Maybe`, `@AsyncSatisfies`)
+- Swift macros (`@specs`, `@AutoContext`)
+
+### SpecificationCore vs SpecificationKit
+
+- **SpecificationCore**: Platform-independent fundamentals. Use this for backend services, CLI tools, or when you don't need platform-specific features.
+- **SpecificationKit**: Builds on Core with SwiftUI integration, platform-specific context providers, and advanced specifications.
+
+## Quick Start
+
+### Creating Your First Specification
+
+```swift
+import SpecificationCore
+
+// Define a simple specification
+struct PremiumUserSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.subscriptionTier == .premium && user.isActive
+ }
+}
+
+// Use the specification
+let spec = PremiumUserSpec()
+let user = User(subscriptionTier: .premium, isActive: true)
+
+if spec.isSatisfiedBy(user) {
+ print("Premium user verified!")
+}
+```
+
+### Composing Specifications
+
+```swift
+// Combine specifications with logical operators
+let eligibilitySpec = PremiumUserSpec()
+ .and(MaxCountSpec(counterKey: "feature_used", maximumCount: 10))
+ .and(TimeSinceEventSpec(eventKey: "last_usage", minimumInterval: 3600))
+
+// Use with property wrapper
+@Satisfies(using: eligibilitySpec)
+var canUseFeature: Bool
+
+if canUseFeature {
+ performPremiumAction()
+}
+```
+
+### Working with Context
+
+```swift
+// Set up context
+let provider = DefaultContextProvider.shared
+provider.setCounter("feature_used", value: 5)
+provider.recordEvent("last_usage")
+
+// Specifications automatically use the context
+@Satisfies(using: MaxCountSpec(counterKey: "feature_used", maximumCount: 10))
+var hasUsesRemaining: Bool // true (5 < 10)
+```
+
+### Decision Making
+
+```swift
+// Make decisions based on multiple specifications
+@Decides([
+ (PremiumUserSpec(), "premium_discount"),
+ (FirstTimeUserSpec(), "welcome_discount"),
+ (RegularUserSpec(), "standard_discount")
+], or: "no_discount")
+var discountType: String
+```
+
+## Topics
+
+### Essentials
+
+-
+-
+-
+-
+
+### Core Protocols
+
+- ``Specification``
+- ``DecisionSpec``
+- ``AsyncSpecification``
+- ``ContextProviding``
+- ``AnySpecification``
+- ``AnyContextProvider``
+
+### Context Infrastructure
+
+- ``EvaluationContext``
+- ``DefaultContextProvider``
+- ``MockContextProvider``
+
+### Basic Specifications
+
+- ``PredicateSpec``
+- ``FirstMatchSpec``
+- ``MaxCountSpec``
+- ``CooldownIntervalSpec``
+- ``TimeSinceEventSpec``
+- ``DateRangeSpec``
+- ``DateComparisonSpec``
+
+### Property Wrappers
+
+- ``Satisfies``
+- ``Decides``
+- ``Maybe``
+- ``AsyncSatisfies``
+
+### Macros
+
+-
+-
+
+### Composition and Operators
+
+-
+
+## See Also
+
+- [SpecificationKit](https://github.com/yourorg/SpecificationKit) - Platform-specific features and SwiftUI integration
+- [Getting Started Tutorial](doc:GettingStartedCore)
+- [GitHub Repository](https://github.com/yourorg/SpecificationCore)
diff --git a/Sources/SpecificationCore/Documentation.docc/SpecificationOperators.md b/Sources/SpecificationCore/Documentation.docc/SpecificationOperators.md
new file mode 100644
index 0000000..63c8b60
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/SpecificationOperators.md
@@ -0,0 +1,529 @@
+# Specification Operators and Builders
+
+Operators, functions, and builders for composing specifications with elegant syntax.
+
+## Overview
+
+SpecificationCore provides a rich set of operators, convenience functions, and builder patterns that make composing specifications more expressive and readable. These utilities complement the core ``Specification`` protocol with Swift-native operators and fluent interfaces.
+
+### What's Included
+
+- **Logical Operators**: `&&`, `||`, `!` for boolean composition
+- **Convenience Functions**: `spec()`, `alwaysTrue()`, `alwaysFalse()` for quick creation
+- **Builder Pattern**: ``SpecificationBuilder`` for fluent composition
+- **Global Functions**: `build()` for starting builder chains
+
+### When to Use These Utilities
+
+Use specification operators and builders when you want to:
+- Write more concise and readable composition code
+- Use familiar Swift operators for logical operations
+- Build specifications fluently with method chaining
+- Create specifications from closures quickly
+- Construct complex specifications step-by-step
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+struct User {
+ let age: Int
+ let isActive: Bool
+ let isPremium: Bool
+}
+
+struct AdultSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.age >= 18
+ }
+}
+
+struct ActiveSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.isActive
+ }
+}
+
+// Using operators
+let eligibleSpec = AdultSpec() && ActiveSpec() || PremiumSpec()
+
+// Using convenience functions
+let customSpec = spec { $0.age >= 21 }
+
+// Using builder pattern
+let builtSpec = build(AdultSpec())
+ .and(ActiveSpec())
+ .or(PremiumSpec())
+ .build()
+```
+
+## Logical Operators
+
+### AND Operator (&&)
+
+Combines two specifications with AND logic:
+
+```swift
+let adultSpec = AdultSpec()
+let activeSpec = ActiveSpec()
+
+// Using method syntax
+let combined1 = adultSpec.and(activeSpec)
+
+// Using operator syntax (more concise)
+let combined2 = adultSpec && activeSpec
+
+// Both are equivalent
+let user = User(age: 25, isActive: true, isPremium: false)
+combined1.isSatisfiedBy(user) // true
+combined2.isSatisfiedBy(user) // true
+```
+
+### OR Operator (||)
+
+Combines two specifications with OR logic:
+
+```swift
+let premiumSpec = PremiumSpec()
+let trialSpec = TrialSpec()
+
+// Using method syntax
+let hasAccess1 = premiumSpec.or(trialSpec)
+
+// Using operator syntax
+let hasAccess2 = premiumSpec || trialSpec
+
+// Satisfied if user is premium OR trial
+hasAccess2.isSatisfiedBy(user)
+```
+
+### NOT Operator (!)
+
+Negates a specification:
+
+```swift
+let activeSpec = ActiveSpec()
+
+// Using method syntax
+let inactive1 = activeSpec.not()
+
+// Using operator syntax (prefix)
+let inactive2 = !activeSpec
+
+// Satisfied when user is NOT active
+inactive2.isSatisfiedBy(user)
+```
+
+### Operator Precedence
+
+Operators follow standard Swift precedence rules:
+
+```swift
+// AND has higher precedence than OR
+let spec1 = adultSpec && activeSpec || premiumSpec
+// Equivalent to:
+let spec2 = (adultSpec && activeSpec) || premiumSpec
+
+// Use parentheses for clarity
+let spec3 = adultSpec && (activeSpec || premiumSpec)
+
+// NOT has highest precedence
+let spec4 = !adultSpec && activeSpec
+// Equivalent to:
+let spec5 = (!adultSpec) && activeSpec
+```
+
+## Complex Composition
+
+Combine operators for complex logic:
+
+```swift
+struct VerifiedSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.emailVerified
+ }
+}
+
+struct BannedSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.isBanned
+ }
+}
+
+// Complex eligibility: (adult AND active) OR premium, AND NOT banned
+let eligibilitySpec =
+ (AdultSpec() && ActiveSpec() || PremiumSpec()) &&
+ !BannedSpec() &&
+ VerifiedSpec()
+
+if eligibilitySpec.isSatisfiedBy(user) {
+ print("User is eligible")
+}
+```
+
+## Convenience Functions
+
+### spec() Function
+
+Create specifications quickly from closures:
+
+```swift
+// Instead of creating a struct
+struct EmailValidSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.email.contains("@")
+ }
+}
+
+// Use spec() for inline creation
+let emailValid = spec { user in
+ user.email.contains("@")
+}
+
+// Even more concise with shorthand
+let emailValid2 = spec { $0.email.contains("@") }
+
+// Compose with other specs
+let verifiedUser = spec { $0.emailVerified } &&
+ spec { $0.age >= 18 }
+```
+
+### alwaysTrue() Function
+
+Create a specification that always returns true:
+
+```swift
+let always = alwaysTrue()
+
+always.isSatisfiedBy(anyUser) // Always true
+
+// Useful for conditional logic
+let spec = isFeatureEnabled
+ ? ActualSpec()
+ : alwaysTrue()
+```
+
+### alwaysFalse() Function
+
+Create a specification that always returns false:
+
+```swift
+let never = alwaysFalse()
+
+never.isSatisfiedBy(anyUser) // Always false
+
+// Useful for disabling features
+let spec = isMaintenanceMode
+ ? alwaysFalse()
+ : NormalSpec()
+```
+
+## Builder Pattern
+
+``SpecificationBuilder`` provides a fluent interface for step-by-step composition:
+
+### Basic Builder Usage
+
+```swift
+let spec = build(AdultSpec())
+ .and(ActiveSpec())
+ .and(VerifiedSpec())
+ .build()
+
+let isEligible = spec.isSatisfiedBy(user)
+```
+
+### Starting with a Predicate
+
+```swift
+let spec = build { $0.age >= 18 }
+ .and(spec { $0.isActive })
+ .and(spec { $0.emailVerified })
+ .build()
+```
+
+### Complex Builder Chains
+
+```swift
+let eligibilitySpec = build(BaseEligibilitySpec())
+ .and(AgeRequirementSpec())
+ .and(LocationSpec())
+ .or(PremiumOverrideSpec()) // Premium users bypass requirements
+ .and(NotBannedSpec()) // But still can't be banned
+ .build()
+```
+
+### Conditional Building
+
+```swift
+var builder = build(BaseSpec())
+
+if requireAdult {
+ builder = builder.and(AdultSpec())
+}
+
+if requireActive {
+ builder = builder.and(ActiveSpec())
+}
+
+if premiumOnly {
+ builder = builder.and(PremiumSpec())
+}
+
+let finalSpec = builder.build()
+```
+
+### Negation in Builder
+
+```swift
+let spec = build(ActiveSpec())
+ .and(VerifiedSpec())
+ .not() // Negate the entire chain
+ .build()
+
+// Equivalent to: !(ActiveSpec() && VerifiedSpec())
+```
+
+## Combining Operators and Builders
+
+Mix operators and builders for maximum flexibility:
+
+```swift
+// Start with operator composition
+let baseSpec = AdultSpec() && ActiveSpec()
+
+// Continue with builder
+let fullSpec = build(baseSpec)
+ .or(PremiumSpec())
+ .and(VerifiedSpec())
+ .build()
+
+// Or use operators on built specs
+let built = build(Spec1()).and(Spec2()).build()
+let final = built && Spec3() || Spec4()
+```
+
+## Real-World Examples
+
+### User Access Control
+
+```swift
+// Readable access control logic
+let canAccessPremiumContent =
+ (spec { $0.subscriptionTier == "premium" } &&
+ spec { $0.subscriptionExpiry > Date() }) ||
+ (spec { $0.isAdmin }) &&
+ !spec { $0.isBanned }
+
+if canAccessPremiumContent.isSatisfiedBy(user) {
+ // Show premium content
+}
+```
+
+### Feature Flag Evaluation
+
+```swift
+// Complex feature flag logic
+let showNewUI = build { ctx in
+ ctx.flag(for: "new_ui_enabled") == true
+}
+.and(spec { ctx in
+ ctx.counter(for: "login_count") ?? 0 >= 5
+})
+.or(spec { ctx in
+ ctx.flag(for: "force_new_ui") == true
+})
+.build()
+
+if showNewUI.isSatisfiedBy(context) {
+ // Render new UI
+}
+```
+
+### Form Validation
+
+```swift
+let isValidRegistration =
+ spec { $0.email.contains("@") } &&
+ spec { $0.password.count >= 8 } &&
+ spec { $0.agreedToTerms } &&
+ (spec { $0.age >= 18 } || spec { $0.hasParentalConsent })
+
+if isValidRegistration.isSatisfiedBy(form) {
+ submitRegistration(form)
+}
+```
+
+### E-Commerce Rules
+
+```swift
+let qualifiesForDiscount = build { order in
+ order.totalAmount >= 100
+}
+.and(spec { $0.itemCount >= 3 })
+.or(spec { $0.customerTier == "VIP" })
+.or(spec { $0.isFirstPurchase })
+.and(!spec { $0.alreadyDiscounted })
+.build()
+
+if qualifiesForDiscount.isSatisfiedBy(order) {
+ applyDiscount(to: order)
+}
+```
+
+## Functional Patterns
+
+### Specification Pipelines
+
+```swift
+let pipeline = [
+ spec { $0.age >= 18 },
+ spec { $0.emailVerified },
+ spec { $0.isActive },
+ spec { !$0.isBanned }
+]
+
+// All must pass
+let allPass = pipeline.allSatisfied()
+
+// Any must pass
+let anyPass = pipeline.anySatisfied()
+```
+
+### Specification Factories
+
+```swift
+func createValidation(for type: UserType) -> AnySpecification {
+ switch type {
+ case .admin:
+ return spec { $0.role == "admin" } &&
+ spec { $0.emailVerified }
+
+ case .moderator:
+ return spec { $0.role == "moderator" } &&
+ spec { $0.age >= 21 } &&
+ spec { $0.backgroundCheckPassed }
+
+ case .user:
+ return spec { $0.emailVerified } &&
+ !spec { $0.isBanned }
+ }
+}
+
+let validation = createValidation(for: .admin)
+```
+
+### Higher-Order Specifications
+
+```swift
+func requireAll(_ requirements: [AnySpecification]) -> AnySpecification {
+ requirements.isEmpty
+ ? alwaysTrue()
+ : requirements.allSatisfied()
+}
+
+func requireAny(_ options: [AnySpecification]) -> AnySpecification {
+ options.isEmpty
+ ? alwaysFalse()
+ : options.anySatisfied()
+}
+
+// Use higher-order functions
+let must = requireAll([
+ spec { $0.age >= 18 },
+ spec { $0.isActive }
+])
+
+let canBe = requireAny([
+ spec { $0.isPremium },
+ spec { $0.isAdmin }
+])
+
+let finalSpec = must && canBe
+```
+
+## Best Practices
+
+### Use Operators for Readability
+
+```swift
+// ✅ Good - concise and readable
+let spec = adultSpec && activeSpec || premiumSpec
+
+// ❌ Verbose - harder to read
+let spec = adultSpec.and(activeSpec).or(premiumSpec)
+```
+
+### Use Builders for Complex Logic
+
+```swift
+// ✅ Good - clear step-by-step construction
+let spec = build(baseSpec)
+ .and(requirement1)
+ .and(requirement2)
+ .or(override)
+ .build()
+
+// ❌ Harder to read - complex operator chain
+let spec = baseSpec && requirement1 && requirement2 || override
+```
+
+### Name Intermediate Specifications
+
+```swift
+// ✅ Good - named intermediate specs
+let hasValidSubscription = premiumSpec || trialSpec
+let meetsAgeRequirement = adultSpec
+let isEligible = hasValidSubscription && meetsAgeRequirement
+
+// ❌ Avoid - unnamed complex chains
+let spec = premiumSpec || trialSpec && adultSpec
+```
+
+### Use spec() for Simple Cases
+
+```swift
+// ✅ Good - inline for simple checks
+let valid = spec { $0.email.contains("@") }
+
+// ❌ Overkill - creating a struct for simple predicate
+struct EmailValidSpec: Specification { /* ... */ }
+let valid = EmailValidSpec()
+```
+
+## Performance Considerations
+
+- **Operator Overhead**: Operators have no performance overhead vs method calls
+- **Builder Allocation**: Builders create intermediate objects; use for readability, not performance-critical paths
+- **Inline Specs**: `spec()` function creates closures; consider reusable structs for frequently called specs
+- **Short-Circuit Evaluation**: && and || operators short-circuit like standard Swift operators
+
+## Topics
+
+### Logical Operators
+
+- ``&&(_:_:)`` (AND)
+- ``||(_:_:)`` (OR)
+- ``!(_:)`` (NOT)
+
+### Convenience Functions
+
+- ``spec(_:)``
+- ``alwaysTrue()``
+- ``alwaysFalse()``
+
+### Builder Pattern
+
+- ``SpecificationBuilder``
+
+### Related Concepts
+
+- ``Specification``
+- ``AnySpecification``
+
+## See Also
+
+-
+- ``AnySpecification``
+- ``SpecificationBuilder``
diff --git a/Sources/SpecificationCore/Documentation.docc/SpecsMacro.md b/Sources/SpecificationCore/Documentation.docc/SpecsMacro.md
new file mode 100644
index 0000000..207b5a5
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/SpecsMacro.md
@@ -0,0 +1,631 @@
+# @specs Macro
+
+A macro that generates composite specifications by combining multiple specification instances with AND logic.
+
+## Overview
+
+The `@specs` macro simplifies creating composite specifications by automatically combining multiple specification instances using `.and()` logic. Instead of manually chaining specifications together, you can declare a specification type with the `@specs` macro and let it generate all the boilerplate code for you.
+
+### Key Benefits
+
+- **Automatic Composition**: Generates `.and()` chains automatically from specification instances
+- **Type-Safe**: Validates that all specifications share the same context type
+- **Compile-Time Validation**: Catches errors like mixed context types and incorrect arguments
+- **Reduced Boilerplate**: Eliminates repetitive composite specification code
+- **Clear Intent**: Declarative syntax makes complex rules easy to understand
+- **Auto Context Integration**: Works seamlessly with ``AutoContext`` macro
+
+### When to Use @specs
+
+Use `@specs` when you need to:
+- Combine multiple specifications with AND logic
+- Create reusable composite specification types
+- Define complex business rules declaratively
+- Reduce boilerplate in specification-heavy code
+- Build eligibility or validation specifications
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+// Without @specs - manual composition
+struct PremiumEligibilitySpec: Specification {
+ typealias T = EvaluationContext
+
+ let spec1 = FeatureFlagSpec(flagKey: "premium_enabled")
+ let spec2 = TimeSinceEventSpec(eventKey: "user_registered", days: 30)
+ let spec3 = MaxCountSpec(counterKey: "violations", maximumCount: 1)
+
+ func isSatisfiedBy(_ candidate: EvaluationContext) -> Bool {
+ return spec1.and(spec2).and(spec3).isSatisfiedBy(candidate)
+ }
+}
+
+// With @specs - automatic composition
+@specs(
+ FeatureFlagSpec(flagKey: "premium_enabled"),
+ TimeSinceEventSpec(eventKey: "user_registered", days: 30),
+ MaxCountSpec(counterKey: "violations", maximumCount: 1)
+)
+struct PremiumEligibilitySpec: Specification {
+ typealias T = EvaluationContext
+}
+```
+
+## How @specs Works
+
+The macro generates the necessary boilerplate to combine specifications:
+
+```swift
+@specs(Spec1(), Spec2(), Spec3())
+struct MyCompositeSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+// Expands to:
+struct MyCompositeSpec: Specification {
+ typealias T = EvaluationContext
+
+ private let composite: AnySpecification
+
+ public init() {
+ let specChain = Spec1().and(Spec2()).and(Spec3())
+ self.composite = AnySpecification(specChain)
+ }
+
+ public func isSatisfiedBy(_ candidate: T) -> Bool {
+ composite.isSatisfiedBy(candidate)
+ }
+
+ public func isSatisfiedByAsync(_ candidate: T) async throws -> Bool {
+ composite.isSatisfiedBy(candidate)
+ }
+}
+```
+
+## Usage Examples
+
+### Basic Eligibility Specification
+
+```swift
+@specs(
+ TimeSinceEventSpec(eventKey: "user_registered", days: 7),
+ FeatureFlagSpec(flagKey: "email_verified"),
+ MaxCountSpec(counterKey: "violations", maximumCount: 0)
+)
+struct RewardEligibilitySpec: Specification {
+ typealias T = EvaluationContext
+}
+
+// Usage
+let spec = RewardEligibilitySpec()
+let context = DefaultContextProvider.shared.currentContext()
+
+if spec.isSatisfiedBy(context) {
+ grantReward()
+}
+```
+
+### API Access Control
+
+```swift
+@specs(
+ MaxCountSpec.dailyLimit("api_calls", limit: 1000),
+ FeatureFlagSpec(flagKey: "api_access_enabled"),
+ CooldownIntervalSpec.hourly("rate_limit_violation").not()
+)
+struct APIAccessSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+func makeAPICall() throws {
+ let spec = APIAccessSpec()
+ let context = DefaultContextProvider.shared.currentContext()
+
+ guard spec.isSatisfiedBy(context) else {
+ throw APIError.accessDenied
+ }
+
+ // Make API call
+}
+```
+
+### Feature Rollout Specification
+
+```swift
+@specs(
+ FeatureFlagSpec(flagKey: "new_feature_enabled"),
+ DateRangeSpec(start: rolloutStart, end: rolloutEnd),
+ UserSegmentSpec(expectedSegment: .beta)
+)
+struct NewFeatureAccessSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+@Satisfies(using: NewFeatureAccessSpec())
+var canAccessNewFeature: Bool
+
+if canAccessNewFeature {
+ showNewFeature()
+}
+```
+
+### Premium Subscription Validation
+
+```swift
+@specs(
+ FeatureFlagSpec(flagKey: "subscription_active"),
+ DateComparisonSpec(
+ eventKey: "subscription_start",
+ comparison: .before,
+ date: Date().addingTimeInterval(365 * 86400) // Within 1 year
+ ),
+ MaxCountSpec(counterKey: "payment_failures", maximumCount: 0)
+)
+struct ActiveSubscriptionSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+func checkSubscriptionAccess() -> Bool {
+ let spec = ActiveSubscriptionSpec()
+ let context = DefaultContextProvider.shared.currentContext()
+ return spec.isSatisfiedBy(context)
+}
+```
+
+## Combining with @AutoContext
+
+The `@specs` macro works seamlessly with ``AutoContext`` for even cleaner code:
+
+```swift
+@specs(
+ FeatureFlagSpec(flagKey: "premium_enabled"),
+ TimeSinceEventSpec(eventKey: "user_registered", days: 30),
+ MaxCountSpec.dailyLimit("premium_actions", limit: 100)
+)
+@AutoContext
+struct PremiumAccessSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+// Usage with auto-context - no provider needed!
+let spec = PremiumAccessSpec()
+
+// Access isSatisfied property (added by @AutoContext)
+if try await spec.isSatisfied {
+ enablePremiumFeatures()
+}
+```
+
+## Real-World Examples
+
+### Multi-Tier Access Control
+
+```swift
+// Free tier - basic checks only
+@specs(
+ FeatureFlagSpec(flagKey: "free_tier_enabled"),
+ MaxCountSpec.dailyLimit("free_actions", limit: 10)
+)
+struct FreeTierSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+// Premium tier - more permissive
+@specs(
+ FeatureFlagSpec(flagKey: "premium_subscription"),
+ MaxCountSpec.dailyLimit("premium_actions", limit: 1000),
+ DateComparisonSpec(
+ eventKey: "subscription_start",
+ comparison: .before,
+ date: Date()
+ )
+)
+struct PremiumTierSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+// Enterprise tier - most permissive
+@specs(
+ FeatureFlagSpec(flagKey: "enterprise_subscription"),
+ MaxCountSpec.dailyLimit("enterprise_actions", limit: 100000),
+ FeatureFlagSpec(flagKey: "priority_support")
+)
+struct EnterpriseTierSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+func getAccessLevel() -> AccessLevel {
+ let context = DefaultContextProvider.shared.currentContext()
+
+ if EnterpriseTierSpec().isSatisfiedBy(context) {
+ return .enterprise
+ } else if PremiumTierSpec().isSatisfiedBy(context) {
+ return .premium
+ } else if FreeTierSpec().isSatisfiedBy(context) {
+ return .free
+ } else {
+ return .none
+ }
+}
+```
+
+### Campaign Eligibility System
+
+```swift
+@specs(
+ DateRangeSpec(start: campaignStart, end: campaignEnd),
+ UserSegmentSpec(expectedSegment: .targetAudience),
+ MaxCountSpec(counterKey: "campaign_participations", maximumCount: 0),
+ TimeSinceEventSpec(eventKey: "user_registered", days: 7),
+ FeatureFlagSpec(flagKey: "campaign_active")
+)
+struct CampaignEligibilitySpec: Specification {
+ typealias T = EvaluationContext
+}
+
+func checkCampaignEligibility() -> (eligible: Bool, reason: String?) {
+ let spec = CampaignEligibilitySpec()
+ let context = DefaultContextProvider.shared.currentContext()
+
+ let eligible = spec.isSatisfiedBy(context)
+
+ if !eligible {
+ // Check individual conditions to provide feedback
+ if !DateRangeSpec(start: campaignStart, end: campaignEnd)
+ .isSatisfiedBy(context) {
+ return (false, "Campaign is not currently active")
+ }
+ if !TimeSinceEventSpec(eventKey: "user_registered", days: 7)
+ .isSatisfiedBy(context) {
+ return (false, "Account must be at least 7 days old")
+ }
+ return (false, "Not eligible for this campaign")
+ }
+
+ return (true, nil)
+}
+```
+
+### Security Gate Specification
+
+```swift
+@specs(
+ FeatureFlagSpec(flagKey: "account_verified"),
+ FeatureFlagSpec(flagKey: "two_factor_enabled"),
+ MaxCountSpec(counterKey: "failed_login_attempts", maximumCount: 3),
+ CooldownIntervalSpec(eventKey: "last_password_change", days: 90).not(),
+ MaxCountSpec(counterKey: "security_violations", maximumCount: 0)
+)
+struct HighSecurityAccessSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+func canAccessSensitiveData() -> Bool {
+ let spec = HighSecurityAccessSpec()
+ let context = DefaultContextProvider.shared.currentContext()
+ return spec.isSatisfiedBy(context)
+}
+
+func performSensitiveOperation() throws {
+ guard canAccessSensitiveData() else {
+ throw SecurityError.insufficientPermissions
+ }
+
+ // Perform operation
+}
+```
+
+### Content Moderation Specification
+
+```swift
+@specs(
+ FeatureFlagSpec(flagKey: "account_in_good_standing"),
+ MaxCountSpec(counterKey: "content_warnings", maximumCount: 2),
+ MaxCountSpec(counterKey: "community_reports", maximumCount: 5),
+ TimeSinceEventSpec(eventKey: "last_violation", days: 30),
+ CooldownIntervalSpec(eventKey: "last_suspension", days: 90)
+)
+struct CanPostContentSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+func validateUserCanPost() -> PostPermission {
+ let spec = CanPostContentSpec()
+ let context = DefaultContextProvider.shared.currentContext()
+
+ if spec.isSatisfiedBy(context) {
+ return .allowed
+ } else {
+ return .restricted(reason: "Account restrictions in effect")
+ }
+}
+```
+
+## Validation and Diagnostics
+
+The `@specs` macro provides compile-time validation:
+
+### Requires Specification Conformance
+
+```swift
+// ❌ Error - must conform to Specification
+@specs(Spec1(), Spec2())
+struct MySpec { // Missing: Specification
+ typealias T = EvaluationContext
+}
+```
+
+### Requires At Least One Argument
+
+```swift
+// ❌ Error - requires at least one specification
+@specs()
+struct EmptySpec: Specification {
+ typealias T = EvaluationContext
+}
+```
+
+### Warns About Missing typealias T
+
+```swift
+// ⚠️ Warning - should add typealias T
+@specs(Spec1(), Spec2())
+struct MySpec: Specification {
+ // Missing: typealias T = EvaluationContext
+}
+```
+
+### Detects Mixed Context Types
+
+```swift
+// ❌ Error - mixed context types
+@specs(
+ MaxCountSpec(counterKey: "count", maximumCount: 10), // EvaluationContext
+ CustomSpec() // OtherContext
+)
+struct MixedSpec: Specification {
+ typealias T = EvaluationContext
+}
+```
+
+### Prevents Async Specifications
+
+```swift
+// ❌ Error - async specifications not supported
+@specs(
+ MaxCountSpec(counterKey: "count", maximumCount: 10),
+ SomeAsyncSpec() // AsyncSpecification not allowed
+)
+struct MySpec: Specification {
+ typealias T = EvaluationContext
+}
+```
+
+### Warns About Type References
+
+```swift
+// ⚠️ Warning - looks like a type reference
+@specs(
+ MaxCountSpec.self, // Should be MaxCountSpec(...)
+ FeatureFlagSpec.self
+)
+struct MySpec: Specification {
+ typealias T = EvaluationContext
+}
+```
+
+## Testing
+
+Test macro-generated specifications like any other:
+
+```swift
+func testCompositeSpecification() {
+ @specs(
+ FeatureFlagSpec(flagKey: "enabled"),
+ MaxCountSpec(counterKey: "count", maximumCount: 10)
+ )
+ struct TestSpec: Specification {
+ typealias T = EvaluationContext
+ }
+
+ let provider = MockContextProvider()
+ .withFlag("enabled", value: true)
+ .withCounter("count", value: 5)
+
+ let spec = TestSpec()
+ let context = provider.currentContext()
+
+ // Both conditions satisfied
+ XCTAssertTrue(spec.isSatisfiedBy(context))
+
+ // Disable flag - should fail
+ provider.setFlag("enabled", to: false)
+ XCTAssertFalse(spec.isSatisfiedBy(context))
+
+ // Exceed count - should fail
+ provider.setFlag("enabled", to: true)
+ provider.setCounter("count", to: 15)
+ XCTAssertFalse(spec.isSatisfiedBy(context))
+}
+
+func testSpecsWithAutoContext() async throws {
+ @specs(
+ FeatureFlagSpec(flagKey: "feature_enabled")
+ )
+ @AutoContext
+ struct AutoSpec: Specification {
+ typealias T = EvaluationContext
+ }
+
+ // Set up test context
+ DefaultContextProvider.shared.setFlag("feature_enabled", to: true)
+
+ let spec = AutoSpec()
+
+ // Test using isSatisfied property
+ let result = try await spec.isSatisfied
+ XCTAssertTrue(result)
+}
+```
+
+## Best Practices
+
+### Use Descriptive Specification Names
+
+```swift
+// ✅ Good - clear intent
+@specs(
+ PremiumUserSpec(),
+ EmailVerifiedSpec(),
+ NoViolationsSpec()
+)
+struct PremiumAccessSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+// ❌ Avoid - unclear purpose
+@specs(
+ Spec1(),
+ Spec2(),
+ Spec3()
+)
+struct ComboSpec: Specification {
+ typealias T = EvaluationContext
+}
+```
+
+### Group Related Specifications
+
+```swift
+// ✅ Good - grouped by concern
+@specs(
+ // Account status
+ FeatureFlagSpec(flagKey: "account_active"),
+ FeatureFlagSpec(flagKey: "email_verified"),
+
+ // Usage limits
+ MaxCountSpec.dailyLimit("api_calls", limit: 1000),
+ CooldownIntervalSpec.hourly("rate_limit"),
+
+ // Security
+ MaxCountSpec(counterKey: "failed_attempts", maximumCount: 3)
+)
+struct SecureAPIAccessSpec: Specification {
+ typealias T = EvaluationContext
+}
+```
+
+### Document Complex Specifications
+
+```swift
+/// Determines eligibility for loyalty rewards program.
+///
+/// Requirements:
+/// - Account registered for at least 30 days
+/// - Email verified
+/// - Made at least 5 purchases
+/// - No account violations
+/// - Loyalty program is currently active
+@specs(
+ TimeSinceEventSpec(eventKey: "user_registered", days: 30),
+ FeatureFlagSpec(flagKey: "email_verified"),
+ MaxCountSpec(counterKey: "purchases", maximumCount: 5).not(),
+ MaxCountSpec(counterKey: "violations", maximumCount: 0),
+ FeatureFlagSpec(flagKey: "loyalty_program_active")
+)
+struct LoyaltyRewardsEligibilitySpec: Specification {
+ typealias T = EvaluationContext
+}
+```
+
+### Combine with Property Wrappers
+
+```swift
+@specs(
+ PremiumSubscriptionSpec(),
+ NoPaymentIssuesSpec(),
+ AccountInGoodStandingSpec()
+)
+struct PremiumAccessSpec: Specification {
+ typealias T = EvaluationContext
+}
+
+// Use with @Satisfies for clean integration
+@Satisfies(using: PremiumAccessSpec())
+var hasPremiumAccess: Bool
+
+if hasPremiumAccess {
+ showPremiumContent()
+}
+```
+
+## Performance Considerations
+
+- **Single Evaluation**: Composite specification is created once at initialization
+- **Chained Evaluation**: Evaluates specifications in order, stops at first failure
+- **No Overhead**: Macro expansion happens at compile time
+- **Type Erasure**: Uses `AnySpecification` for type erasure (minimal overhead)
+- **Short-Circuit Logic**: AND logic stops at first false result
+
+## Comparison with Manual Composition
+
+### Manual Composition
+
+```swift
+struct ManualCompositeSpec: Specification {
+ typealias T = EvaluationContext
+
+ private let spec1 = FeatureFlagSpec(flagKey: "enabled")
+ private let spec2 = MaxCountSpec(counterKey: "count", maximumCount: 10)
+ private let spec3 = TimeSinceEventSpec(eventKey: "start", days: 7)
+
+ func isSatisfiedBy(_ candidate: EvaluationContext) -> Bool {
+ return spec1.and(spec2).and(spec3).isSatisfiedBy(candidate)
+ }
+}
+```
+
+### With @specs Macro
+
+```swift
+@specs(
+ FeatureFlagSpec(flagKey: "enabled"),
+ MaxCountSpec(counterKey: "count", maximumCount: 10),
+ TimeSinceEventSpec(eventKey: "start", days: 7)
+)
+struct MacroCompositeSpec: Specification {
+ typealias T = EvaluationContext
+}
+```
+
+**Benefits of @specs**:
+- Less boilerplate (no manual property declarations)
+- Clearer intent (specifications listed declaratively)
+- Consistent pattern across codebase
+- Automatic validation at compile time
+- Less room for implementation errors
+
+## Topics
+
+### Macro Usage
+
+
+
+### Related Macros
+
+-
+
+### Related Types
+
+- ``Specification``
+- ``AnySpecification``
+- ``EvaluationContext``
+
+## See Also
+
+-
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/TimeSinceEventSpec.md b/Sources/SpecificationCore/Documentation.docc/TimeSinceEventSpec.md
new file mode 100644
index 0000000..4f27070
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/TimeSinceEventSpec.md
@@ -0,0 +1,576 @@
+# ``SpecificationCore/TimeSinceEventSpec``
+
+A specification that checks if a minimum duration has passed since a specific event.
+
+## Overview
+
+`TimeSinceEventSpec` verifies that sufficient time has elapsed since an event was recorded. It's useful for implementing delays, cooldown periods, or time-based restrictions where you need to ensure a minimum time has passed before allowing an action.
+
+### Key Benefits
+
+- **Minimum Time Enforcement**: Ensure enough time has passed before proceeding
+- **Flexible Time Units**: Specify durations in seconds, minutes, hours, or days
+- **Event-Based Tracking**: Works with ``EvaluationContext`` event timestamps
+- **App Launch Tracking**: Special support for time since app launch
+- **Readable API**: Clear, expressive time unit extensions
+
+### When to Use TimeSinceEventSpec
+
+Use `TimeSinceEventSpec` when you need to:
+- Enforce minimum wait times between actions
+- Delay feature availability after onboarding
+- Implement tutorial or welcome flows
+- Check if enough time has passed since user registration
+- Verify minimum session duration
+
+## Quick Example
+
+```swift
+import SpecificationCore
+
+// Record user registration
+let provider = DefaultContextProvider.shared
+provider.recordEvent("user_registered")
+
+// Check if user has been registered for at least 7 days
+let eligibilitySpec = TimeSinceEventSpec(
+ eventKey: "user_registered",
+ days: 7
+)
+
+@Satisfies(using: eligibilitySpec)
+var isEligibleForReward: Bool
+
+if isEligibleForReward {
+ grantLoyaltyReward()
+}
+```
+
+## Creating TimeSinceEventSpec
+
+### Basic Creation
+
+```swift
+// With TimeInterval (seconds)
+let spec1 = TimeSinceEventSpec(
+ eventKey: "first_launch",
+ minimumInterval: 300 // 5 minutes
+)
+
+// With time unit convenience init
+let spec2 = TimeSinceEventSpec(
+ eventKey: "first_launch",
+ minutes: 5
+)
+```
+
+### Time Unit Initializers
+
+```swift
+// Seconds
+let shortDelay = TimeSinceEventSpec(
+ eventKey: "tutorial_started",
+ seconds: 30
+)
+
+// Minutes
+let mediumDelay = TimeSinceEventSpec(
+ eventKey: "onboarding_completed",
+ minutes: 15
+)
+
+// Hours
+let longDelay = TimeSinceEventSpec(
+ eventKey: "account_created",
+ hours: 24
+)
+
+// Days
+let veryLongDelay = TimeSinceEventSpec(
+ eventKey: "user_registered",
+ days: 30
+)
+```
+
+## How It Works
+
+The specification checks if enough time has passed since the event:
+
+```swift
+let spec = TimeSinceEventSpec(eventKey: "action", hours: 1)
+
+// Event never occurred: satisfied ✅ (no wait needed)
+// Event 30 minutes ago: NOT satisfied ❌ (not enough time)
+// Event 1 hour ago: satisfied ✅ (exactly enough time)
+// Event 2 hours ago: satisfied ✅ (more than enough time)
+```
+
+## Usage Examples
+
+### Onboarding Delay
+
+```swift
+// Record when user completes onboarding
+provider.recordEvent("onboarding_completed")
+
+// Show advanced features after 1 hour of app use
+let advancedFeaturesSpec = TimeSinceEventSpec(
+ eventKey: "onboarding_completed",
+ hours: 1
+)
+
+@Satisfies(using: advancedFeaturesSpec)
+var canShowAdvancedFeatures: Bool
+
+if canShowAdvancedFeatures {
+ showAdvancedTutorial()
+}
+```
+
+### Loyalty Program Eligibility
+
+```swift
+// Check if user has been member for 30 days
+let loyaltySpec = TimeSinceEventSpec(
+ eventKey: "user_registered",
+ days: 30
+)
+
+@Satisfies(using: loyaltySpec)
+var isLoyaltyEligible: Bool
+
+func checkLoyaltyRewards() {
+ if isLoyaltyEligible {
+ unlockLoyaltyTier()
+ } else {
+ showIneligibleMessage()
+ }
+}
+```
+
+### Trial Period Verification
+
+```swift
+// Check if trial period has expired (14 days)
+let trialSpec = TimeSinceEventSpec(
+ eventKey: "trial_started",
+ days: 14
+)
+
+@Satisfies(using: trialSpec)
+var isTrialExpired: Bool
+
+if isTrialExpired {
+ showUpgradePrompt()
+}
+```
+
+### Feature Unlock Timing
+
+```swift
+// Unlock advanced features after 3 days of usage
+let featureUnlockSpec = TimeSinceEventSpec(
+ eventKey: "app_first_launch",
+ days: 3
+)
+
+@Satisfies(using: featureUnlockSpec)
+var canAccessAdvancedFeatures: Bool
+
+struct FeatureView: View {
+ var body: some View {
+ if canAccessAdvancedFeatures {
+ AdvancedFeaturePanel()
+ } else {
+ LockedFeatureMessage()
+ }
+ }
+}
+```
+
+## App Launch Tracking
+
+Special support for checking time since app launch:
+
+```swift
+// Minimum 5 minutes since launch
+let launchDelaySpec = TimeSinceEventSpec.sinceAppLaunch(minutes: 5)
+
+@Satisfies(using: launchDelaySpec)
+var hasBeenRunningLongEnough: Bool
+
+// Show rating prompt after app has been open for a while
+if hasBeenRunningLongEnough {
+ showRatingPrompt()
+}
+```
+
+### Available App Launch Methods
+
+```swift
+// Seconds
+let spec1 = TimeSinceEventSpec.sinceAppLaunch(seconds: 30)
+
+// Minutes
+let spec2 = TimeSinceEventSpec.sinceAppLaunch(minutes: 5)
+
+// Hours
+let spec3 = TimeSinceEventSpec.sinceAppLaunch(hours: 1)
+
+// Days
+let spec4 = TimeSinceEventSpec.sinceAppLaunch(days: 1)
+```
+
+## TimeInterval Extensions
+
+Readable time constants for specifications:
+
+```swift
+import SpecificationCore
+
+// Use TimeInterval extension methods
+let spec1 = TimeSinceEventSpec(
+ eventKey: "action",
+ minimumInterval: .seconds(30)
+)
+
+let spec2 = TimeSinceEventSpec(
+ eventKey: "action",
+ minimumInterval: .minutes(5)
+)
+
+let spec3 = TimeSinceEventSpec(
+ eventKey: "action",
+ minimumInterval: .hours(2)
+)
+
+let spec4 = TimeSinceEventSpec(
+ eventKey: "action",
+ minimumInterval: .days(7)
+)
+
+let spec5 = TimeSinceEventSpec(
+ eventKey: "action",
+ minimumInterval: .weeks(2)
+)
+```
+
+## Real-World Examples
+
+### Welcome Flow Timing
+
+```swift
+class WelcomeFlowManager {
+ let provider = DefaultContextProvider.shared
+
+ // Show different welcome messages based on time since registration
+ let newUserSpec = TimeSinceEventSpec(
+ eventKey: "user_registered",
+ days: 0 // Just registered
+ )
+
+ let weekOldSpec = TimeSinceEventSpec(
+ eventKey: "user_registered",
+ days: 7
+ )
+
+ let monthOldSpec = TimeSinceEventSpec(
+ eventKey: "user_registered",
+ days: 30
+ )
+
+ func getWelcomeMessage() -> String {
+ let context = provider.currentContext()
+
+ if !newUserSpec.isSatisfiedBy(context) {
+ return "Welcome! Let's get started."
+ } else if !weekOldSpec.isSatisfiedBy(context) {
+ return "Welcome back! Enjoying the app?"
+ } else if !monthOldSpec.isSatisfiedBy(context) {
+ return "Thanks for sticking with us!"
+ } else {
+ return "Welcome back, valued member!"
+ }
+ }
+}
+```
+
+### Progressive Feature Disclosure
+
+```swift
+struct FeatureGate {
+ let provider = DefaultContextProvider.shared
+
+ // Unlock features progressively over time
+ enum Feature {
+ case basic
+ case intermediate
+ case advanced
+ case expert
+
+ var unlockSpec: TimeSinceEventSpec {
+ switch self {
+ case .basic:
+ return TimeSinceEventSpec(
+ eventKey: "app_first_launch",
+ days: 0 // Immediate
+ )
+ case .intermediate:
+ return TimeSinceEventSpec(
+ eventKey: "app_first_launch",
+ days: 3
+ )
+ case .advanced:
+ return TimeSinceEventSpec(
+ eventKey: "app_first_launch",
+ days: 7
+ )
+ case .expert:
+ return TimeSinceEventSpec(
+ eventKey: "app_first_launch",
+ days: 14
+ )
+ }
+ }
+ }
+
+ func isUnlocked(_ feature: Feature) -> Bool {
+ let context = provider.currentContext()
+ return feature.unlockSpec.isSatisfiedBy(context)
+ }
+}
+```
+
+### Rating Prompt Strategy
+
+```swift
+class RatingPromptManager {
+ let provider = DefaultContextProvider.shared
+
+ // Wait for 7 days AND 10+ sessions before asking for rating
+ let timeRequirement = TimeSinceEventSpec(
+ eventKey: "app_first_launch",
+ days: 7
+ )
+
+ let usageRequirement = MaxCountSpec(
+ counterKey: "app_sessions",
+ maximumCount: 10
+ ).not() // More than 10 sessions
+
+ var shouldPromptForRating: Bool {
+ let context = provider.currentContext()
+ return timeRequirement.isSatisfiedBy(context) &&
+ usageRequirement.isSatisfiedBy(context)
+ }
+
+ func promptIfAppropriate() {
+ guard shouldPromptForRating else { return }
+
+ requestAppStoreReview()
+ // Record to prevent repeated prompts
+ provider.recordEvent("rating_prompted")
+ }
+}
+```
+
+### Subscription Grace Period
+
+```swift
+class SubscriptionManager {
+ let provider = DefaultContextProvider.shared
+
+ // Allow 3-day grace period after subscription expiration
+ let gracePeriodSpec = TimeSinceEventSpec(
+ eventKey: "subscription_expired",
+ days: 3
+ ).not() // NOT yet 3 days past expiration
+
+ var isInGracePeriod: Bool {
+ let context = provider.currentContext()
+ return gracePeriodSpec.isSatisfiedBy(context)
+ }
+
+ func checkAccess() -> AccessLevel {
+ if isActiveSubscription {
+ return .full
+ } else if isInGracePeriod {
+ return .grace
+ } else {
+ return .expired
+ }
+ }
+}
+```
+
+## Testing
+
+Test time-based logic with ``MockContextProvider``:
+
+```swift
+func testRecentEvent() {
+ // Event occurred 5 minutes ago
+ let fiveMinutesAgo = Date().addingTimeInterval(-300)
+
+ let provider = MockContextProvider()
+ .withEvent("action", date: fiveMinutesAgo)
+
+ let spec = TimeSinceEventSpec(eventKey: "action", minutes: 10)
+
+ // Should NOT be satisfied (5 min < 10 min)
+ XCTAssertFalse(spec.isSatisfiedBy(provider.currentContext()))
+}
+
+func testOldEvent() {
+ // Event occurred 1 hour ago
+ let oneHourAgo = Date().addingTimeInterval(-3600)
+
+ let provider = MockContextProvider()
+ .withEvent("action", date: oneHourAgo)
+
+ let spec = TimeSinceEventSpec(eventKey: "action", minutes: 30)
+
+ // Should be satisfied (60 min > 30 min)
+ XCTAssertTrue(spec.isSatisfiedBy(provider.currentContext()))
+}
+
+func testNoEvent() {
+ let provider = MockContextProvider()
+
+ let spec = TimeSinceEventSpec(eventKey: "never_happened", hours: 1)
+
+ // Should be satisfied (no event = no wait required)
+ XCTAssertTrue(spec.isSatisfiedBy(provider.currentContext()))
+}
+
+func testAppLaunchTiming() {
+ // App launched 10 minutes ago
+ let provider = MockContextProvider.launchDelayScenario(
+ timeSinceLaunch: 600 // 10 minutes
+ )
+
+ let spec = TimeSinceEventSpec.sinceAppLaunch(minutes: 5)
+
+ // Should be satisfied (10 min > 5 min)
+ XCTAssertTrue(spec.isSatisfiedBy(provider.currentContext()))
+}
+```
+
+## Best Practices
+
+### Use Readable Time Units
+
+```swift
+// ✅ Good - clear intent
+let spec = TimeSinceEventSpec(eventKey: "registration", days: 30)
+
+// ❌ Less clear - requires mental calculation
+let spec = TimeSinceEventSpec(eventKey: "registration", seconds: 2592000)
+```
+
+### Record Events at Appropriate Times
+
+```swift
+// ✅ Good - record when event actually occurs
+func completeOnboarding() {
+ finishOnboarding()
+ provider.recordEvent("onboarding_completed")
+}
+
+// ❌ Avoid - recording before event completes
+func completeOnboarding() {
+ provider.recordEvent("onboarding_completed")
+ finishOnboarding() // Might fail
+}
+```
+
+### Choose Appropriate Minimum Times
+
+```swift
+// ✅ Good - reasonable timeframes
+let newUserPeriod = TimeSinceEventSpec(eventKey: "registered", days: 7)
+let trialPeriod = TimeSinceEventSpec(eventKey: "trial_start", days: 14)
+
+// ❌ Avoid - unreasonable timeframes
+let newUserPeriod = TimeSinceEventSpec(eventKey: "registered", seconds: 10)
+```
+
+### Use Descriptive Event Keys
+
+```swift
+// ✅ Good - clear, specific keys
+"user_registered"
+"onboarding_completed"
+"subscription_started"
+
+// ❌ Avoid - ambiguous keys
+"event1"
+"start"
+"done"
+```
+
+## Comparison with CooldownIntervalSpec
+
+`TimeSinceEventSpec` and ``CooldownIntervalSpec`` are similar but have different use cases:
+
+### TimeSinceEventSpec
+- **Purpose**: Verify minimum time has passed
+- **Returns True When**: Event never occurred OR enough time has passed
+- **Use For**: One-time delays, eligibility checks, progressive disclosure
+
+### CooldownIntervalSpec
+- **Purpose**: Enforce cooldown periods for repeated actions
+- **Returns True When**: Event never occurred OR cooldown has expired
+- **Use For**: Throttling, rate limiting, notification control
+
+```swift
+// TimeSinceEventSpec: "Has it been at least X time since Y?"
+let eligibility = TimeSinceEventSpec(
+ eventKey: "user_registered",
+ days: 30
+)
+
+// CooldownIntervalSpec: "Can we do X again? (enough time since last time)"
+let canNotify = CooldownIntervalSpec(
+ eventKey: "last_notification",
+ hours: 1
+)
+```
+
+## Performance Considerations
+
+- **Event Lookup**: O(1) dictionary access
+- **Date Arithmetic**: Simple subtraction operation
+- **No Side Effects**: Read-only evaluation
+- **Missing Events**: Returns true immediately
+- **Context Creation**: Lightweight operation
+
+## Topics
+
+### Creating Specifications
+
+- ``init(eventKey:minimumInterval:)``
+- ``init(eventKey:seconds:)``
+- ``init(eventKey:minutes:)``
+- ``init(eventKey:hours:)``
+- ``init(eventKey:days:)``
+
+### App Launch Tracking
+
+- ``sinceAppLaunch(minimumInterval:)``
+- ``sinceAppLaunch(seconds:)``
+- ``sinceAppLaunch(minutes:)``
+- ``sinceAppLaunch(hours:)``
+- ``sinceAppLaunch(days:)``
+
+### Properties
+
+- ``eventKey``
+- ``minimumInterval``
+
+## See Also
+
+-
+-
+-
+-
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/GettingStartedCore.tutorial b/Sources/SpecificationCore/Documentation.docc/Tutorials/GettingStartedCore.tutorial
new file mode 100644
index 0000000..06dffd6
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/GettingStartedCore.tutorial
@@ -0,0 +1,153 @@
+@Tutorial(time: 25) {
+ @Intro(title: "Getting Started with SpecificationCore") {
+ Learn how to implement the Specification Pattern in Swift using SpecificationCore. Create your first specifications, compose rules with logical operators, and evaluate them with context providers.
+
+ The Specification Pattern helps you:
+ - Separate business logic from UI and data layers
+ - Create reusable and composable business rules
+ - Write more testable code
+ - Maintain clean architecture
+ }
+
+ @Section(title: "Understanding Specifications") {
+ @ContentAndMedia {
+ A specification encapsulates a business rule that can be evaluated against a candidate. The ``Specification`` protocol is the foundation of SpecificationCore.
+ }
+
+ @Steps {
+ @Step {
+ Import SpecificationCore and define a model to evaluate.
+
+ @Code(name: "MyFirstSpec.swift", file: "getting-started-01-first-spec.swift")
+ }
+
+ @Step {
+ Create your first specification by implementing the ``Specification`` protocol.
+
+ @Code(name: "MyFirstSpec.swift", file: "getting-started-01-first-spec-02.swift")
+ }
+
+ @Step {
+ Test the specification with sample data.
+
+ @Code(name: "MyFirstSpec.swift", file: "getting-started-01-first-spec-03.swift")
+ }
+ }
+ }
+
+ @Section(title: "Using Context and Providers") {
+ @ContentAndMedia {
+ ``EvaluationContext`` provides runtime data like events, counters, and timestamps. Use ``DefaultContextProvider`` to manage context across your app.
+ }
+
+ @Steps {
+ @Step {
+ Create a context provider and record events.
+
+ @Code(name: "ContextExample.swift", file: "getting-started-02-with-context.swift")
+ }
+
+ @Step {
+ Use built-in specifications that leverage context data.
+
+ @Code(name: "ContextExample.swift", file: "getting-started-02-with-context-02.swift")
+ }
+ }
+ }
+
+ @Section(title: "Composing Specifications") {
+ @ContentAndMedia {
+ Combine specifications using logical operators (AND, OR, NOT) to build complex business rules from simple primitives.
+ }
+
+ @Steps {
+ @Step {
+ Create multiple simple specifications.
+
+ @Code(name: "CompositionExample.swift", file: "getting-started-03-composition.swift")
+ }
+
+ @Step {
+ Combine specifications using operators.
+
+ @Code(name: "CompositionExample.swift", file: "getting-started-03-composition-02.swift")
+ }
+
+ @Step {
+ Test the composed specification.
+
+ @Code(name: "CompositionExample.swift", file: "getting-started-03-composition-03.swift")
+ }
+ }
+ }
+
+ @Section(title: "Built-in Specifications") {
+ @ContentAndMedia {
+ SpecificationCore provides ready-to-use specifications for common patterns like rate limiting, time-based rules, and feature flags.
+ }
+
+ @Steps {
+ @Step {
+ Use ``MaxCountSpec`` for rate limiting.
+
+ @Code(name: "BuiltInSpecs.swift", file: "getting-started-04-built-in-specs.swift")
+ }
+
+ @Step {
+ Use ``TimeSinceEventSpec`` for cooldown periods.
+
+ @Code(name: "BuiltInSpecs.swift", file: "getting-started-04-built-in-specs-02.swift")
+ }
+
+ @Step {
+ Combine built-in specs for complex rules.
+
+ @Code(name: "BuiltInSpecs.swift", file: "getting-started-04-built-in-specs-03.swift")
+ }
+ }
+ }
+
+ @Section(title: "Testing Specifications") {
+ @ContentAndMedia {
+ Use ``MockContextProvider`` to create predictable test scenarios for your specifications.
+ }
+
+ @Steps {
+ @Step {
+ Write unit tests using MockContextProvider.
+
+ @Code(name: "SpecTests.swift", file: "getting-started-05-testing.swift")
+ }
+ }
+ }
+
+ @Assessments {
+ @MultipleChoice {
+ What protocol do you implement to create a custom specification?
+
+ @Choice(isCorrect: false) {
+ `BusinessRule`
+
+ @Justification(reaction: "Try again!") {
+ SpecificationCore uses the `Specification` protocol.
+ }
+ }
+
+ @Choice(isCorrect: true) {
+ `Specification`
+
+ @Justification(reaction: "Correct!") {
+ The `Specification` protocol is the foundation for all business rules in SpecificationCore.
+ }
+ }
+
+ @Choice(isCorrect: false) {
+ `Rule`
+
+ @Justification(reaction: "Try again!") {
+ SpecificationCore uses the `Specification` protocol.
+ }
+ }
+ }
+ }
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/MacrosAndAdvanced.tutorial b/Sources/SpecificationCore/Documentation.docc/Tutorials/MacrosAndAdvanced.tutorial
new file mode 100644
index 0000000..804412a
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/MacrosAndAdvanced.tutorial
@@ -0,0 +1,115 @@
+@Tutorial(time: 25) {
+ @Intro(title: "Macros and Advanced Composition") {
+ Learn how to use Swift macros for elegant specification composition and build complex, real-world business rules. This tutorial covers the @specs and @AutoContext macros along with advanced testing patterns.
+ }
+
+ @Section(title: "@specs Macro for Composition") {
+ @ContentAndMedia {
+ The `@specs` macro enables declarative composition of specifications, reducing boilerplate and improving readability.
+ }
+
+ @Steps {
+ @Step {
+ Create composite specifications declaratively with @specs.
+
+ @Code(name: "SpecsMacroExample.swift", file: "macros-01-specs-basic.swift")
+ }
+
+ @Step {
+ Build complex multi-condition specifications.
+
+ @Code(name: "ComplexSpecsExample.swift", file: "macros-01-specs-complex.swift")
+ }
+ }
+ }
+
+ @Section(title: "@AutoContext Macro") {
+ @ContentAndMedia {
+ The `@AutoContext` macro automatically injects context provider access into your specifications, enabling cleaner evaluation patterns.
+ }
+
+ @Steps {
+ @Step {
+ Use @AutoContext for automatic provider injection.
+
+ @Code(name: "AutoContextExample.swift", file: "macros-02-auto-context.swift")
+ }
+
+ @Step {
+ Combine @specs and @AutoContext for maximum expressiveness.
+
+ @Code(name: "CombinedMacrosExample.swift", file: "macros-02-combined.swift")
+ }
+ }
+ }
+
+ @Section(title: "Complex Real-World Specifications") {
+ @ContentAndMedia {
+ Build production-ready specifications for common use cases like promotional banners, subscription upgrades, and feature gating.
+ }
+
+ @Steps {
+ @Step {
+ Create e-commerce promotional specifications.
+
+ @Code(name: "ECommerceSpec.swift", file: "macros-03-ecommerce.swift")
+ }
+
+ @Step {
+ Build subscription and access control specifications.
+
+ @Code(name: "SubscriptionSpec.swift", file: "macros-03-subscription.swift")
+ }
+ }
+ }
+
+ @Section(title: "Testing and Best Practices") {
+ @ContentAndMedia {
+ Use ``MockContextProvider`` to create predictable, isolated test scenarios for complex specifications.
+ }
+
+ @Steps {
+ @Step {
+ Test complex specifications with MockContextProvider.
+
+ @Code(name: "SpecificationTests.swift", file: "macros-04-testing.swift")
+ }
+
+ @Step {
+ Follow best practices for specification design.
+
+ @Code(name: "BestPractices.swift", file: "macros-04-best-practices.swift")
+ }
+ }
+ }
+
+ @Assessments {
+ @MultipleChoice {
+ What is the primary benefit of using composite specifications?
+
+ @Choice(isCorrect: false) {
+ They execute faster than simple specifications.
+
+ @Justification(reaction: "Try again!") {
+ Performance is similar; the benefit is in code organization.
+ }
+ }
+
+ @Choice(isCorrect: true) {
+ They encapsulate complex business rules into reusable components.
+
+ @Justification(reaction: "Correct!") {
+ Composite specifications bundle related rules together, improving maintainability and reusability.
+ }
+ }
+
+ @Choice(isCorrect: false) {
+ They automatically persist state.
+
+ @Justification(reaction: "Try again!") {
+ Specifications are stateless; state is managed by context providers.
+ }
+ }
+ }
+ }
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/PropertyWrappersGuide.tutorial b/Sources/SpecificationCore/Documentation.docc/Tutorials/PropertyWrappersGuide.tutorial
new file mode 100644
index 0000000..bd88751
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/PropertyWrappersGuide.tutorial
@@ -0,0 +1,79 @@
+@Tutorial(time: 20) {
+ @Intro(title: "Property Wrappers for Declarative Evaluation") {
+ Learn how to use SpecificationCore's property wrappers for clean, declarative specification evaluation. Property wrappers like ``Satisfies``, ``Decides``, and ``Maybe`` simplify specification usage throughout your application.
+ }
+
+ @Section(title: "@Satisfies Basics") {
+ @ContentAndMedia {
+ The ``Satisfies`` property wrapper automatically handles context retrieval and specification evaluation, providing a simple boolean property.
+ }
+
+ @Steps {
+ @Step {
+ Use @Satisfies with a built-in specification.
+
+ @Code(name: "SatisfiesExample.swift", file: "property-wrappers-01-satisfies-basic.swift")
+ }
+
+ @Step {
+ Use @Satisfies with inline predicates for simple conditions.
+
+ @Code(name: "SatisfiesExample.swift", file: "property-wrappers-01-satisfies-basic-02.swift")
+ }
+ }
+ }
+
+ @Section(title: "Decision Specifications") {
+ @ContentAndMedia {
+ Use ``Decides`` for specifications that return typed values instead of booleans, and ``Maybe`` for optional results with fallbacks.
+ }
+
+ @Steps {
+ @Step {
+ Use @Decides to route to different values based on conditions.
+
+ @Code(name: "DecisionExample.swift", file: "property-wrappers-02-decides.swift")
+ }
+
+ @Step {
+ Use @Maybe for optional results with default fallbacks.
+
+ @Code(name: "MaybeExample.swift", file: "property-wrappers-02-maybe.swift")
+ }
+ }
+ }
+
+ @Section(title: "Async Specifications") {
+ @ContentAndMedia {
+ Use ``AsyncSatisfies`` for specifications that require asynchronous evaluation.
+ }
+
+ @Steps {
+ @Step {
+ Create async specifications with @AsyncSatisfies.
+
+ @Code(name: "AsyncExample.swift", file: "property-wrappers-03-async.swift")
+ }
+ }
+ }
+
+ @Section(title: "Advanced Patterns") {
+ @ContentAndMedia {
+ Combine property wrappers with builder patterns and projected values for maximum flexibility.
+ }
+
+ @Steps {
+ @Step {
+ Use the builder pattern for complex specifications.
+
+ @Code(name: "AdvancedExample.swift", file: "property-wrappers-04-advanced.swift")
+ }
+
+ @Step {
+ Use convenience factory methods.
+
+ @Code(name: "FactoryExample.swift", file: "property-wrappers-04-advanced-02.swift")
+ }
+ }
+ }
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-01-first-spec-02.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-01-first-spec-02.swift
new file mode 100644
index 0000000..aa74de2
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-01-first-spec-02.swift
@@ -0,0 +1,15 @@
+import SpecificationCore
+
+// Define a model to evaluate
+struct User {
+ let name: String
+ let age: Int
+ let isPremium: Bool
+}
+
+// Create a specification that checks if a user is an adult
+struct AdultUserSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.age >= 18
+ }
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-01-first-spec-03.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-01-first-spec-03.swift
new file mode 100644
index 0000000..5e04068
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-01-first-spec-03.swift
@@ -0,0 +1,24 @@
+import SpecificationCore
+
+// Define a model to evaluate
+struct User {
+ let name: String
+ let age: Int
+ let isPremium: Bool
+}
+
+// Create a specification that checks if a user is an adult
+struct AdultUserSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.age >= 18
+ }
+}
+
+// Test the specification
+let adultSpec = AdultUserSpec()
+
+let alice = User(name: "Alice", age: 25, isPremium: false)
+let bob = User(name: "Bob", age: 16, isPremium: true)
+
+print(adultSpec.isSatisfiedBy(alice)) // true
+print(adultSpec.isSatisfiedBy(bob)) // false
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-01-first-spec.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-01-first-spec.swift
new file mode 100644
index 0000000..3bd9455
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-01-first-spec.swift
@@ -0,0 +1,8 @@
+import SpecificationCore
+
+// Define a model to evaluate
+struct User {
+ let name: String
+ let age: Int
+ let isPremium: Bool
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-02-with-context-02.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-02-with-context-02.swift
new file mode 100644
index 0000000..dabaa71
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-02-with-context-02.swift
@@ -0,0 +1,26 @@
+import SpecificationCore
+
+// Create a context provider and set up state
+let provider = DefaultContextProvider.shared
+
+// Record events for time-based tracking
+provider.recordEvent("last_login")
+provider.recordEvent("tutorial_completed")
+
+// Set counters for usage tracking
+provider.setCounter("app_launches", to: 5)
+provider.incrementCounter("page_views")
+
+// Set feature flags
+provider.setFlag("premium_features", to: true)
+
+// Use built-in specifications with context
+let maxShowsSpec = MaxCountSpec(counterKey: "banner_shown", maximumCount: 3)
+
+// Evaluate against the current context
+let context = provider.currentContext()
+let canShowBanner = maxShowsSpec.isSatisfiedBy(context)
+print("Can show banner: \(canShowBanner)") // true (counter is 0)
+
+// After showing the banner, increment the counter
+provider.incrementCounter("banner_shown")
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-02-with-context.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-02-with-context.swift
new file mode 100644
index 0000000..f15b623
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-02-with-context.swift
@@ -0,0 +1,19 @@
+import SpecificationCore
+
+// Create a context provider and set up state
+let provider = DefaultContextProvider.shared
+
+// Record events for time-based tracking
+provider.recordEvent("last_login")
+provider.recordEvent("tutorial_completed")
+
+// Set counters for usage tracking
+provider.setCounter("app_launches", to: 5)
+provider.incrementCounter("page_views")
+
+// Set feature flags
+provider.setFlag("premium_features", to: true)
+
+// Get the current context for evaluation
+let context = provider.currentContext()
+print("App launches: \(context.counter(for: "app_launches"))")
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-03-composition-02.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-03-composition-02.swift
new file mode 100644
index 0000000..a9d4cf0
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-03-composition-02.swift
@@ -0,0 +1,37 @@
+import SpecificationCore
+
+struct User {
+ let name: String
+ let age: Int
+ let isPremium: Bool
+ let country: String
+}
+
+struct AdultUserSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.age >= 18
+ }
+}
+
+struct PremiumUserSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.isPremium
+ }
+}
+
+struct USResidentSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.country == "US"
+ }
+}
+
+// Combine specifications using logical operators
+let adultSpec = AdultUserSpec()
+let premiumSpec = PremiumUserSpec()
+let usResidentSpec = USResidentSpec()
+
+// User must be adult AND (premium OR US resident)
+let eligibleSpec = adultSpec.and(premiumSpec.or(usResidentSpec))
+
+// User must NOT be a minor
+let notMinorSpec = adultSpec.not().not() // Same as adultSpec
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-03-composition-03.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-03-composition-03.swift
new file mode 100644
index 0000000..43ac9b1
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-03-composition-03.swift
@@ -0,0 +1,42 @@
+import SpecificationCore
+
+struct User {
+ let name: String
+ let age: Int
+ let isPremium: Bool
+ let country: String
+}
+
+struct AdultUserSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.age >= 18
+ }
+}
+
+struct PremiumUserSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.isPremium
+ }
+}
+
+struct USResidentSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.country == "US"
+ }
+}
+
+let adultSpec = AdultUserSpec()
+let premiumSpec = PremiumUserSpec()
+let usResidentSpec = USResidentSpec()
+
+// User must be adult AND (premium OR US resident)
+let eligibleSpec = adultSpec.and(premiumSpec.or(usResidentSpec))
+
+// Test with different users
+let alice = User(name: "Alice", age: 25, isPremium: true, country: "UK")
+let bob = User(name: "Bob", age: 30, isPremium: false, country: "US")
+let charlie = User(name: "Charlie", age: 16, isPremium: true, country: "US")
+
+print(eligibleSpec.isSatisfiedBy(alice)) // true (adult + premium)
+print(eligibleSpec.isSatisfiedBy(bob)) // true (adult + US)
+print(eligibleSpec.isSatisfiedBy(charlie)) // false (not adult)
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-03-composition.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-03-composition.swift
new file mode 100644
index 0000000..c287b3b
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-03-composition.swift
@@ -0,0 +1,27 @@
+import SpecificationCore
+
+struct User {
+ let name: String
+ let age: Int
+ let isPremium: Bool
+ let country: String
+}
+
+// Create focused, single-responsibility specifications
+struct AdultUserSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.age >= 18
+ }
+}
+
+struct PremiumUserSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.isPremium
+ }
+}
+
+struct USResidentSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.country == "US"
+ }
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-04-built-in-specs-02.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-04-built-in-specs-02.swift
new file mode 100644
index 0000000..9b7db23
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-04-built-in-specs-02.swift
@@ -0,0 +1,19 @@
+import SpecificationCore
+
+let provider = DefaultContextProvider.shared
+
+// TimeSinceEventSpec: Check time elapsed since an event
+let cooldownSpec = TimeSinceEventSpec(
+ eventKey: "last_notification",
+ minimumInterval: 3600 // 1 hour in seconds
+)
+
+// Record when we showed a notification
+provider.recordEvent("last_notification")
+
+// Later, check if enough time has passed
+let context = provider.currentContext()
+if cooldownSpec.isSatisfiedBy(context) {
+ print("Enough time has passed, can show notification")
+ provider.recordEvent("last_notification")
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-04-built-in-specs-03.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-04-built-in-specs-03.swift
new file mode 100644
index 0000000..6301689
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-04-built-in-specs-03.swift
@@ -0,0 +1,21 @@
+import SpecificationCore
+
+let provider = DefaultContextProvider.shared
+
+// Combine built-in specs for complex rules
+let maxShows = MaxCountSpec(counterKey: "promo_shown", maximumCount: 5)
+let cooldown = TimeSinceEventSpec(eventKey: "last_promo", minimumInterval: 86400)
+
+// Show promo only if under limit AND cooldown passed
+let canShowPromo = maxShows.and(cooldown)
+
+let context = provider.currentContext()
+if canShowPromo.isSatisfiedBy(context) {
+ showPromotion()
+ provider.incrementCounter("promo_shown")
+ provider.recordEvent("last_promo")
+}
+
+func showPromotion() {
+ print("Displaying promotion...")
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-04-built-in-specs.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-04-built-in-specs.swift
new file mode 100644
index 0000000..eef7317
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-04-built-in-specs.swift
@@ -0,0 +1,17 @@
+import SpecificationCore
+
+let provider = DefaultContextProvider.shared
+
+// MaxCountSpec: Limit how many times something can happen
+let maxBannerShows = MaxCountSpec(counterKey: "banner_shown", maximumCount: 3)
+
+// Check if we can show the banner
+let context = provider.currentContext()
+if maxBannerShows.isSatisfiedBy(context) {
+ print("Showing banner...")
+ provider.incrementCounter("banner_shown")
+}
+
+// Convenience factory methods
+let onlyOnce = MaxCountSpec.onlyOnce("welcome_shown")
+let dailyLimit = MaxCountSpec.dailyLimit("api_calls", limit: 100)
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-05-testing.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-05-testing.swift
new file mode 100644
index 0000000..00a23d8
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-05-testing.swift
@@ -0,0 +1,44 @@
+import SpecificationCore
+import XCTest
+
+final class SpecificationTests: XCTestCase {
+ func testMaxCountSpec() {
+ // Create a fresh provider for testing
+ let provider = MockContextProvider()
+
+ // Set up test state
+ provider.setCounter("banner_shown", to: 2)
+
+ let spec = MaxCountSpec(counterKey: "banner_shown", maximumCount: 3)
+ let context = provider.currentContext()
+
+ // Counter is 2, max is 3, so should be satisfied
+ XCTAssertTrue(spec.isSatisfiedBy(context))
+
+ // Increment to 3
+ provider.setCounter("banner_shown", to: 3)
+ let updatedContext = provider.currentContext()
+
+ // Now at limit, should not be satisfied
+ XCTAssertFalse(spec.isSatisfiedBy(updatedContext))
+ }
+
+ func testComposedSpecification() {
+ struct AgeSpec: Specification {
+ let minAge: Int
+ func isSatisfiedBy(_ age: Int) -> Bool {
+ age >= minAge
+ }
+ }
+
+ let adultSpec = AgeSpec(minAge: 18)
+ let seniorSpec = AgeSpec(minAge: 65)
+
+ // Adult but not senior
+ let middleAgedSpec = adultSpec.and(seniorSpec.not())
+
+ XCTAssertTrue(middleAgedSpec.isSatisfiedBy(30))
+ XCTAssertFalse(middleAgedSpec.isSatisfiedBy(16))
+ XCTAssertFalse(middleAgedSpec.isSatisfiedBy(70))
+ }
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-01-specs-basic.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-01-specs-basic.swift
new file mode 100644
index 0000000..ef0863e
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-01-specs-basic.swift
@@ -0,0 +1,22 @@
+import SpecificationCore
+
+// Create composite specifications using @specs macro
+// Note: Requires SpecificationCoreMacros module
+
+// Traditional approach (without macro)
+struct BannerEligibilitySpec: Specification {
+ typealias T = EvaluationContext
+
+ let timeSinceLaunch = TimeSinceEventSpec.sinceAppLaunch(seconds: 10)
+ let maxCount = MaxCountSpec(counterKey: "banner_shown", maximumCount: 3)
+ let cooldown = CooldownIntervalSpec(eventKey: "last_banner", days: 1)
+
+ func isSatisfiedBy(_ context: EvaluationContext) -> Bool {
+ timeSinceLaunch.isSatisfiedBy(context) && maxCount.isSatisfiedBy(context)
+ && cooldown.isSatisfiedBy(context)
+ }
+}
+
+// With predefined CompositeSpec
+let promoBanner = CompositeSpec.promoBanner
+let ratingPrompt = CompositeSpec.ratingPrompt
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-01-specs-complex.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-01-specs-complex.swift
new file mode 100644
index 0000000..9b89b82
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-01-specs-complex.swift
@@ -0,0 +1,49 @@
+import SpecificationCore
+
+// Build complex multi-condition specifications
+struct FeatureGatingSpec: Specification {
+ typealias T = EvaluationContext
+
+ private let composite: AnySpecification
+
+ init(
+ featureFlag: String,
+ minAppLaunches: Int = 5,
+ requirePremium: Bool = false
+ ) {
+ var specs: [AnySpecification] = []
+
+ // Feature must be enabled
+ specs.append(
+ AnySpecification { context in
+ context.flag(for: featureFlag)
+ })
+
+ // User must have launched app minimum times
+ specs.append(
+ AnySpecification { context in
+ context.counter(for: "app_launches") >= minAppLaunches
+ })
+
+ // Optional premium requirement
+ if requirePremium {
+ specs.append(
+ AnySpecification { context in
+ context.flag(for: "is_premium")
+ })
+ }
+
+ composite = specs.allSatisfied()
+ }
+
+ func isSatisfiedBy(_ context: EvaluationContext) -> Bool {
+ composite.isSatisfiedBy(context)
+ }
+}
+
+// Usage
+let advancedFeature = FeatureGatingSpec(
+ featureFlag: "advanced_analytics",
+ minAppLaunches: 10,
+ requirePremium: true
+)
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-02-auto-context.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-02-auto-context.swift
new file mode 100644
index 0000000..7db29d0
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-02-auto-context.swift
@@ -0,0 +1,35 @@
+import SpecificationCore
+
+// @AutoContext enables automatic context provider access
+// The macro synthesizes an isSatisfied property that uses the default provider
+
+// Without @AutoContext - manual context access
+struct ManualBannerSpec: Specification {
+ typealias T = EvaluationContext
+
+ func isSatisfiedBy(_ context: EvaluationContext) -> Bool {
+ context.counter(for: "banner_shown") < 3 && context.timeSinceLaunch >= 10
+ }
+
+ // Manual evaluation requires provider
+ func evaluate(using provider: some ContextProviding) -> Bool {
+ isSatisfiedBy(provider.currentContext())
+ }
+}
+
+// With @AutoContext (when using SpecificationCoreMacros)
+// @AutoContext
+// struct AutoBannerSpec: Specification {
+// typealias T = EvaluationContext
+//
+// func isSatisfiedBy(_ context: EvaluationContext) -> Bool {
+// context.counter(for: "banner_shown") < 3
+// }
+//
+// // Synthesized: var isSatisfied: Bool (uses DefaultContextProvider.shared)
+// }
+
+// Usage pattern
+let spec = ManualBannerSpec()
+let context = DefaultContextProvider.shared.currentContext()
+let canShow = spec.isSatisfiedBy(context)
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-02-combined.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-02-combined.swift
new file mode 100644
index 0000000..77c0d46
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-02-combined.swift
@@ -0,0 +1,45 @@
+import SpecificationCore
+
+// Combine patterns for maximum expressiveness
+
+// Create a reusable specification factory
+enum SpecificationFactory {
+ // Promotional content specifications
+ static func promoBanner(
+ maxShows: Int = 3,
+ cooldownHours: TimeInterval = 24
+ ) -> AnySpecification {
+ let maxCount = MaxCountSpec(counterKey: "promo_shown", maximumCount: maxShows)
+ let cooldown = CooldownIntervalSpec(eventKey: "last_promo", hours: cooldownHours)
+ return AnySpecification(maxCount.and(cooldown))
+ }
+
+ // Feature gating specifications
+ static func featureGate(
+ flag: String,
+ requiresEngagement: Bool = false
+ ) -> AnySpecification {
+ var specs: [AnySpecification] = [
+ AnySpecification { $0.flag(for: flag) }
+ ]
+
+ if requiresEngagement {
+ specs.append(AnySpecification { $0.counter(for: "sessions") >= 5 })
+ }
+
+ return specs.allSatisfied()
+ }
+
+ // Rate limiting specifications
+ static func rateLimit(
+ action: String,
+ maxPerHour: Int
+ ) -> AnySpecification {
+ AnySpecification(MaxCountSpec(counterKey: "\(action)_hourly", maximumCount: maxPerHour))
+ }
+}
+
+// Usage
+let promo = SpecificationFactory.promoBanner(maxShows: 2, cooldownHours: 48)
+let feature = SpecificationFactory.featureGate(flag: "new_ui", requiresEngagement: true)
+let rateLimit = SpecificationFactory.rateLimit(action: "api_call", maxPerHour: 100)
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-03-ecommerce.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-03-ecommerce.swift
new file mode 100644
index 0000000..440e378
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-03-ecommerce.swift
@@ -0,0 +1,53 @@
+import SpecificationCore
+
+// Real-world e-commerce promotional specifications
+
+struct ECommercePromoSpec: Specification {
+ typealias T = EvaluationContext
+
+ private let composite: AnySpecification
+
+ init() {
+ // Show promo when:
+ // 1. User browsed for at least 2 minutes
+ // 2. Viewed at least 3 products
+ // 3. No purchase in last 24 hours
+ // 4. No promo shown in last 4 hours
+
+ let browsingTime = TimeSinceEventSpec.sinceAppLaunch(minutes: 2)
+ let productViews = PredicateSpec.counter(
+ "products_viewed",
+ .greaterThanOrEqual,
+ 3
+ )
+ let noPurchaseRecently = CooldownIntervalSpec(eventKey: "last_purchase", hours: 24)
+ let promoCooldown = CooldownIntervalSpec(eventKey: "last_promo", hours: 4)
+
+ composite = AnySpecification(
+ browsingTime
+ .and(AnySpecification(productViews))
+ .and(AnySpecification(noPurchaseRecently))
+ .and(AnySpecification(promoCooldown))
+ )
+ }
+
+ func isSatisfiedBy(_ context: EvaluationContext) -> Bool {
+ composite.isSatisfiedBy(context)
+ }
+}
+
+// Usage
+let provider = DefaultContextProvider.shared
+provider.setCounter("products_viewed", to: 5)
+
+let promoSpec = ECommercePromoSpec()
+let context = provider.currentContext()
+
+if promoSpec.isSatisfiedBy(context) {
+ showDiscountBanner()
+ provider.recordEvent("last_promo")
+}
+
+func showDiscountBanner() {
+ print("10% off your next purchase!")
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-03-subscription.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-03-subscription.swift
new file mode 100644
index 0000000..44cec75
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-03-subscription.swift
@@ -0,0 +1,71 @@
+import SpecificationCore
+
+// Subscription upgrade prompt specifications
+
+struct UpgradePromptSpec: Specification {
+ typealias T = EvaluationContext
+
+ private let composite: AnySpecification
+
+ init() {
+ // Show upgrade prompt when:
+ // 1. User has been active for 7+ days
+ // 2. Used premium features 5+ times
+ // 3. Is NOT already a premium subscriber
+ // 4. Haven't shown upgrade prompt in 3 days
+ // 5. Has opened app 10+ times
+
+ let activeUser = PredicateSpec.counter(
+ "days_active",
+ .greaterThanOrEqual,
+ 7
+ )
+ let premiumUsage = PredicateSpec.counter(
+ "premium_feature_usage",
+ .greaterThanOrEqual,
+ 5
+ )
+ let notPremium = PredicateSpec.flag(
+ "is_premium",
+ equals: false
+ )
+ let promptCooldown = CooldownIntervalSpec(eventKey: "last_upgrade_prompt", days: 3)
+ let engagedUser = PredicateSpec.counter(
+ "app_opens",
+ .greaterThanOrEqual,
+ 10
+ )
+
+ composite = AnySpecification(
+ activeUser
+ .and(AnySpecification(premiumUsage))
+ .and(AnySpecification(notPremium))
+ .and(AnySpecification(promptCooldown))
+ .and(AnySpecification(engagedUser))
+ )
+ }
+
+ func isSatisfiedBy(_ context: EvaluationContext) -> Bool {
+ composite.isSatisfiedBy(context)
+ }
+}
+
+// Tiered access control
+struct TierAccessSpec: Specification {
+ typealias T = EvaluationContext
+
+ let requiredTier: String
+
+ func isSatisfiedBy(_ context: EvaluationContext) -> Bool {
+ guard let userTier = context.userData["subscription_tier"] as? String else {
+ return false
+ }
+ let tierOrder = ["free", "basic", "premium", "enterprise"]
+ guard let userIndex = tierOrder.firstIndex(of: userTier),
+ let requiredIndex = tierOrder.firstIndex(of: requiredTier)
+ else {
+ return false
+ }
+ return userIndex >= requiredIndex
+ }
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-04-best-practices.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-04-best-practices.swift
new file mode 100644
index 0000000..003c2a6
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-04-best-practices.swift
@@ -0,0 +1,59 @@
+import SpecificationCore
+
+// Best Practices for Specification Design
+
+// 1. Keep specifications focused and single-purpose
+struct IsAdultSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.age >= 18
+ }
+}
+
+// 2. Use descriptive names that explain the business rule
+struct CanReceiveMarketingEmailsSpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.hasOptedInToMarketing && user.emailVerified
+ }
+}
+
+// 3. Compose complex rules from simple specifications
+let eligibleForPromo = IsAdultSpec()
+ .and(CanReceiveMarketingEmailsSpec())
+
+// 4. Use factory methods for common configurations
+extension MaxCountSpec {
+ static func dailyAPILimit() -> MaxCountSpec {
+ MaxCountSpec(counterKey: "daily_api_calls", maximumCount: 1000)
+ }
+}
+
+// 5. Document business rules in specification comments
+/// Determines if a user qualifies for the loyalty program.
+/// Requirements:
+/// - Account age >= 90 days
+/// - Total purchases >= $100
+/// - No fraud flags
+struct LoyaltyProgramEligibilitySpec: Specification {
+ func isSatisfiedBy(_ user: User) -> Bool {
+ user.accountAgeDays >= 90 && user.totalPurchaseAmount >= 100 && !user.hasFraudFlag
+ }
+}
+
+// 6. Use type-safe keys for counters and events
+enum ContextKey {
+ static let bannerShown = "banner_shown"
+ static let lastPromo = "last_promo"
+ static let appLaunches = "app_launches"
+}
+
+let spec = MaxCountSpec(counterKey: ContextKey.bannerShown, maximumCount: 3)
+
+// Supporting types
+struct User {
+ let age: Int
+ let hasOptedInToMarketing: Bool
+ let emailVerified: Bool
+ let accountAgeDays: Int
+ let totalPurchaseAmount: Double
+ let hasFraudFlag: Bool
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-04-testing.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-04-testing.swift
new file mode 100644
index 0000000..aa320f3
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-04-testing.swift
@@ -0,0 +1,60 @@
+import SpecificationCore
+import XCTest
+
+final class ComplexSpecificationTests: XCTestCase {
+ var mockProvider: MockContextProvider!
+
+ override func setUp() {
+ super.setUp()
+ mockProvider = MockContextProvider()
+ }
+
+ func testPromoSpecShowsForEngagedUser() {
+ // Setup: User has viewed products and no recent promo
+ mockProvider.setCounter("products_viewed", to: 5)
+ mockProvider.setCounter("app_launches", to: 10)
+
+ let spec = ECommercePromoSpec()
+ let context = mockProvider.currentContext()
+
+ // Should show promo for engaged user
+ XCTAssertTrue(spec.isSatisfiedBy(context))
+ }
+
+ func testPromoSpecHidesAfterRecentPurchase() {
+ // Setup: User has purchased recently
+ mockProvider.setCounter("products_viewed", to: 5)
+ mockProvider.recordEvent("last_purchase") // Just now
+
+ let spec = ECommercePromoSpec()
+ let context = mockProvider.currentContext()
+
+ // Should NOT show promo after recent purchase
+ XCTAssertFalse(spec.isSatisfiedBy(context))
+ }
+
+ func testUpgradePromptForFreemiumUser() {
+ // Setup: Active free user who uses premium features
+ mockProvider.setCounter("days_active", to: 14)
+ mockProvider.setCounter("premium_feature_usage", to: 8)
+ mockProvider.setCounter("app_opens", to: 25)
+ mockProvider.setFlag("is_premium", to: false)
+
+ let spec = UpgradePromptSpec()
+ let context = mockProvider.currentContext()
+
+ XCTAssertTrue(spec.isSatisfiedBy(context))
+ }
+
+ func testUpgradePromptHiddenForPremiumUser() {
+ // Setup: Already premium
+ mockProvider.setCounter("days_active", to: 14)
+ mockProvider.setFlag("is_premium", to: true)
+
+ let spec = UpgradePromptSpec()
+ let context = mockProvider.currentContext()
+
+ // Premium users should NOT see upgrade prompt
+ XCTAssertFalse(spec.isSatisfiedBy(context))
+ }
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-01-satisfies-basic-02.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-01-satisfies-basic-02.swift
new file mode 100644
index 0000000..ad0fdf8
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-01-satisfies-basic-02.swift
@@ -0,0 +1,31 @@
+import SpecificationCore
+
+struct FeatureManager {
+ // Use inline predicate for simple conditions
+ @Satisfies(predicate: { context in
+ context.counter(for: "app_launches") >= 3
+ })
+ var hasUsedAppEnough: Bool
+
+ // Use convenience factory methods
+ @Satisfies(using: MaxCountSpec.onlyOnce("welcome_shown"))
+ var shouldShowWelcome: Bool
+
+ // Combine conditions with allOf
+ @Satisfies(allOf: [
+ AnySpecification(MaxCountSpec(counterKey: "banner_shown", maximumCount: 3)),
+ AnySpecification { context in context.flag(for: "banners_enabled") }
+ ])
+ var canShowBannerWithFlag: Bool
+
+ func onAppLaunch() {
+ if shouldShowWelcome {
+ showWelcomeScreen()
+ DefaultContextProvider.shared.incrementCounter("welcome_shown")
+ }
+ }
+
+ func showWelcomeScreen() {
+ print("Welcome!")
+ }
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-01-satisfies-basic.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-01-satisfies-basic.swift
new file mode 100644
index 0000000..cdbb778
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-01-satisfies-basic.swift
@@ -0,0 +1,21 @@
+import SpecificationCore
+
+struct FeatureManager {
+ // Use @Satisfies with a built-in specification
+ @Satisfies(using: MaxCountSpec(counterKey: "banner_shown", maximumCount: 3))
+ var canShowBanner: Bool
+
+ // Use with custom provider
+ @Satisfies(
+ provider: DefaultContextProvider.shared,
+ using: MaxCountSpec(counterKey: "promo_shown", maximumCount: 5)
+ )
+ var canShowPromo: Bool
+
+ func checkFeatures() {
+ if canShowBanner {
+ print("Showing banner...")
+ DefaultContextProvider.shared.incrementCounter("banner_shown")
+ }
+ }
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-02-decides.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-02-decides.swift
new file mode 100644
index 0000000..8b9e45c
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-02-decides.swift
@@ -0,0 +1,32 @@
+import SpecificationCore
+
+// Define tiers for decision routing
+enum SubscriptionTier: String {
+ case free
+ case basic
+ case premium
+}
+
+struct SubscriptionManager {
+ // @Decides returns typed values based on specification matches
+ @Decides(
+ provider: DefaultContextProvider.shared,
+ using: FirstMatchSpec(cases: [
+ (AnySpecification { $0.flag(for: "is_premium") }, SubscriptionTier.premium),
+ (AnySpecification { $0.flag(for: "is_basic") }, SubscriptionTier.basic)
+ ]),
+ default: .free
+ )
+ var currentTier: SubscriptionTier
+
+ func displayContent() {
+ switch currentTier {
+ case .premium:
+ print("Showing all premium features")
+ case .basic:
+ print("Showing basic features")
+ case .free:
+ print("Showing free tier content")
+ }
+ }
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-02-maybe.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-02-maybe.swift
new file mode 100644
index 0000000..7989e0f
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-02-maybe.swift
@@ -0,0 +1,28 @@
+import SpecificationCore
+
+struct ContentManager {
+ // @Maybe returns optional results - nil if no match
+ @Maybe(
+ provider: DefaultContextProvider.shared,
+ using: FirstMatchSpec(cases: [
+ (AnySpecification { $0.flag(for: "show_promo_a") }, "Summer Sale!"),
+ (AnySpecification { $0.flag(for: "show_promo_b") }, "Holiday Discount!")
+ ])
+ )
+ var promoMessage: String?
+
+ func displayPromo() {
+ if let message = promoMessage {
+ print("Promo: \(message)")
+ } else {
+ print("No active promotions")
+ }
+ }
+}
+
+// Setup flags
+let provider = DefaultContextProvider.shared
+provider.setFlag("show_promo_a", to: true)
+
+let manager = ContentManager()
+manager.displayPromo() // "Promo: Summer Sale!"
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-03-async.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-03-async.swift
new file mode 100644
index 0000000..a4b0a08
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-03-async.swift
@@ -0,0 +1,27 @@
+import SpecificationCore
+
+struct AsyncFeatureManager {
+ @Satisfies(using: MaxCountSpec(counterKey: "api_calls", maximumCount: 100))
+ var canMakeAPICall: Bool
+
+ // Use projected value for async evaluation
+ func checkAPILimitAsync() async throws -> Bool {
+ // Access async evaluation via $propertyName
+ try await $canMakeAPICall.evaluateAsync()
+ }
+
+ func makeAPICallIfAllowed() async throws {
+ // Synchronous check
+ guard canMakeAPICall else {
+ print("API limit reached")
+ return
+ }
+
+ // Or async check
+ let allowed = try await checkAPILimitAsync()
+ if allowed {
+ print("Making API call...")
+ DefaultContextProvider.shared.incrementCounter("api_calls")
+ }
+ }
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-04-advanced-02.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-04-advanced-02.swift
new file mode 100644
index 0000000..3bc3333
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-04-advanced-02.swift
@@ -0,0 +1,35 @@
+import SpecificationCore
+
+struct ConvenienceExample {
+ // Use factory methods for common patterns
+
+ // Time-based: true after 10 seconds since launch
+ @Satisfies(predicate: { $0.timeSinceLaunch >= 10 })
+ var hasBeenOpenLongEnough: Bool
+
+ // Counter-based: true while counter < 5
+ @Satisfies(using: MaxCountSpec.counter("views", limit: 5))
+ var canShowMoreViews: Bool
+
+ // Flag-based using predicate
+ @Satisfies(predicate: { $0.flag(for: "dark_mode") })
+ var isDarkModeEnabled: Bool
+
+ // Cooldown-based
+ @Satisfies(predicate: { context in
+ guard let lastEvent = context.event(for: "last_notification") else {
+ return true
+ }
+ return context.currentDate.timeIntervalSince(lastEvent) >= 3600
+ })
+ var canShowNotification: Bool
+}
+
+// Usage
+let provider = DefaultContextProvider.shared
+provider.setFlag("dark_mode", to: true)
+provider.setCounter("views", to: 2)
+
+let example = ConvenienceExample()
+print("Dark mode: \(example.isDarkModeEnabled)") // true
+print("Can show views: \(example.canShowMoreViews)") // true
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-04-advanced.swift b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-04-advanced.swift
new file mode 100644
index 0000000..cf5d0a4
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-04-advanced.swift
@@ -0,0 +1,28 @@
+import SpecificationCore
+
+struct AdvancedFeatureManager {
+ // Use the builder pattern for complex specifications
+ var canShowFeature: Satisfies =
+ .builder(provider: DefaultContextProvider.shared)
+ .with(MaxCountSpec(counterKey: "feature_shown", maximumCount: 5))
+ .with { context in context.flag(for: "feature_enabled") }
+ .with { context in context.timeSinceLaunch >= 10 }
+ .buildAll() // All conditions must be met
+
+ // Or use anyOf for OR logic
+ var hasAccess: Satisfies =
+ .builder(provider: DefaultContextProvider.shared)
+ .with { context in context.flag(for: "is_premium") }
+ .with { context in context.flag(for: "is_staff") }
+ .buildAny() // Any condition can be met
+
+ func checkAccess() {
+ if canShowFeature.wrappedValue {
+ print("Feature available")
+ }
+
+ if hasAccess.wrappedValue {
+ print("Access granted")
+ }
+ }
+}
diff --git a/Sources/SpecificationCore/Documentation.docc/Tutorials/Tutorials.tutorial b/Sources/SpecificationCore/Documentation.docc/Tutorials/Tutorials.tutorial
new file mode 100644
index 0000000..7bbfa4f
--- /dev/null
+++ b/Sources/SpecificationCore/Documentation.docc/Tutorials/Tutorials.tutorial
@@ -0,0 +1,25 @@
+@Tutorials(name: "SpecificationCore Tutorials") {
+ @Intro(title: "Learn the Specification Pattern") {
+ Master the Specification pattern in Swift using SpecificationCore. Learn to build testable, composable business rules from simple primitives to advanced macro-assisted patterns.
+ }
+
+ @Chapter(name: "Getting Started") {
+ Create and compose your first specifications using SpecificationCore's foundational types.
+
+ @TutorialReference(tutorial: "doc:GettingStartedCore")
+ }
+
+ @Chapter(name: "Property Wrappers") {
+ Use declarative property wrappers for clean, reactive specification evaluation.
+
+ @TutorialReference(tutorial: "doc:PropertyWrappersGuide")
+ }
+
+ @Chapter(name: "Macros and Advanced Patterns") {
+ Leverage Swift macros for elegant specification composition and complex business rules.
+
+ @TutorialReference(tutorial: "doc:MacrosAndAdvanced")
+ }
+
+
+}