# Aphoria Comparison Modes

Guide to choosing the right comparison mode for your claims.

## Available Modes

### 1. Equals (exact match)
**Use when:** The observed value must be exactly this value.

**Example:**
```toml
concept_path = "maxwell/core/wallet/atomics/ordering"
predicate = "pattern"
value = "SeqCst"
comparison = "equals"
```

Passes if observation = "SeqCst", fails otherwise.

---

### 2. NotEquals (exact mismatch)
**Use when:** The observed value must NOT be exactly this value (but other values are OK).

**Example:**
```toml
concept_path = "maxwell/crypto/algorithm"
predicate = "algorithm"
value = "md5"
comparison = "not_equals"
```

Passes if observation = "sha256", fails if observation = "md5".

---

### 3. Present (existence check)
**Use when:** Something must exist at this path (don't care about value).

**Example:**
```toml
concept_path = "maxwell/tls/cert_verification"
predicate = "enabled"
value = true
comparison = "present"
```

Passes if ANY observation exists at this path, fails if none found.

---

### 4. Absent (non-existence check)
**Use when:** Nothing should exist at this path.

**Example:**
```toml
concept_path = "maxwell/core/imports/tokio"
predicate = "imported"
value = true
comparison = "absent"
```

Passes if NO observations at this path, fails if any found.

**Note:** Use `NotContains` if you want to forbid a specific value while allowing others.

---

### 5. Contains (substring/list check) ⭐ NEW
**Use when:** The observed value must contain this substring or list element.

**Example 1: List element**
```toml
concept_path = "maxwell/message/derives"
predicate = "traits"
value = "Serialize"
comparison = "contains"
```

Passes if observation = "Clone,Debug,Serialize" (contains "Serialize").
Fails if observation = "Clone,Debug" (doesn't contain "Serialize").

**Example 2: Substring**
```toml
concept_path = "maxwell/config/description"
predicate = "text"
value = "production"
comparison = "contains"
```

Passes if observation = "production environment config".
Fails if observation = "development config".

---

### 6. NotContains (forbidden substring/list element) ⭐ NEW
**Use when:** The observed value must NOT contain this substring or list element.

**Example 1: Forbidden derive**
```toml
concept_path = "maxwell/core/wallet/type/wallet/derives"
predicate = "traits"
value = "Clone"
comparison = "not_contains"
```

Passes if observation = "Debug" (no Clone).
Passes if observation = "Debug,Copy" (no Clone).
**Fails** if observation = "Clone,Debug" (contains Clone).

**Example 2: Forbidden substring**
```toml
concept_path = "maxwell/api/endpoint"
predicate = "path"
value = "/admin"
comparison = "not_contains"
```

Passes if observation = "/api/users".
**Fails** if observation = "/admin/users" (contains "/admin").

---

## Decision Tree

```
Do you care about the value?
├─ NO: Use "present" (must exist) or "absent" (must not exist)
└─ YES: Continue...

Is it a list/comma-separated value?
├─ YES: Use "contains" or "not_contains"
└─ NO: Continue...

Do you need exact match?
├─ YES: Use "equals" (must be X) or "not_equals" (must not be X)
└─ NO: Use "contains" or "not_contains" for partial matching
```

---

## Common Patterns

### Pattern 1: Forbid specific derive trait
```toml
comparison = "not_contains"
value = "Clone"
```
Catches Clone even if other derives present.

### Pattern 2: Require specific derive trait
```toml
comparison = "contains"
value = "Serialize"
```
Ensures Serialize is in the derives list.

### Pattern 3: Forbid exact value
```toml
comparison = "absent"
value = true
```
Use when you want NO observations at all (not just forbidden values).

### Pattern 4: Require exact value
```toml
comparison = "equals"
value = "SeqCst"
```
Use for constants, exact configuration values, exact orderings.

---

## Limitations

### Current (v0.1.0)
- ❌ No regex pattern matching (use "contains" for simple substring)
- ❌ No cross-observation rules ("if X then Y")
- ❌ No composition ("present AND contains")

### Future Enhancements
- Regex mode: `comparison = "regex", value = "md5|sha1"`
- Multi-value: `comparison = "contains_all", value = ["Serialize", "Deserialize"]`
- Conditional: `if_predicate = "imported", then_predicate = "version"`