cce54358d2
**Git Commit Tracking** - Automatically capture git commit hash when claims/observations are ingested - Store in assertion metadata for temporal context and audit trails - Graceful degradation in non-git environments - Solves double-commit problem by capturing hash at ingestion time **Implementation** - walker/git.rs: get_current_commit_hash() utility function - bridge.rs: Accept optional git_commit parameter in all conversion functions - episteme/local: Store project_root, capture git hash during ingestion - 5 new tests for git hash tracking + metadata validation - All 1162 aphoria tests passing **Documentation Overhaul** - README: Added Observations vs Claims distinction, git tracking, dashboard - CLI Reference: New sections for git integration and ignore/exclusion system - Comprehensive ignore documentation: .aphoriaignore, inline comments, 4 methods - Enhanced verification engine docs with matching capabilities - DOCUMENTATION_UPDATES.md: Complete audit summary **Dashboard Separation** - Moved Aphoria-specific UI from stemedb-dashboard to aphoria-dashboard - Clean separation of concerns: StemeDB for core, Aphoria for security - Added dashboard documentation and setup guides 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"`
|