9bfa626203
Major documentation restructure to improve discoverability and reduce duplication. ## Changes **Deleted (Archived/Consolidated)**: - Removed duplicate getting started guides - Archived outdated planning documents - Consolidated corpus and configuration docs - Removed obsolete vision/spec files (superseded by vision.md) - Cleaned up scrapyard and old PDFs **New Structure**: - docs/about/ - Project overview and introduction - docs/guides/ - User guides (moved from root) - docs/specs/ - Technical specifications - docs/sdk/ - SDK documentation (Go) - docs/references/ - API references - docs/archive/ - Archived historical docs - applications/aphoria/docs/advanced/ - Advanced topics - applications/aphoria/docs/reference/ - CLI reference - applications/aphoria/docs/archive/ - Archived aphoria docs **Updated**: - README.md - New root README with clear navigation - CONTRIBUTING.md - Contribution guidelines - CLAUDE.md - Updated paths to new structure - roadmap.md - Added recent completions ## Files Changed - 57 files changed - 1,977 insertions(+) - 961 deletions(-) **Net change**: +1,016 lines (added CONTRIBUTING.md, README.md, reorganized content) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
185 lines
4.2 KiB
Markdown
185 lines
4.2 KiB
Markdown
# 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"`
|