stemedb/applications/aphoria/docs/comparison-modes.md

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:

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:

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:

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:

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

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

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

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

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

comparison = "not_contains"
value = "Clone"

Catches Clone even if other derives present.

Pattern 2: Require specific derive trait

comparison = "contains"
value = "Serialize"

Ensures Serialize is in the derives list.

Pattern 3: Forbid exact value

comparison = "absent"
value = true

Use when you want NO observations at all (not just forbidden values).

Pattern 4: Require exact value

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"