stemedb/ai-lookup/features/phase7-uat.md

Phase 7 UAT: The Shield

Status: Ready for Testing Target Date: 2026-02-03 Confidence: High (7A, 7B complete; 7C core complete)

Summary

Phase 7 (The Shield) defends against spam, Sybil attacks, and knowledge poisoning. This UAT validates the trust-at-scale infrastructure for opening Episteme to millions of agents.

Scope:

• 7A Admission Control: PoW-based spam protection, trust tiers, graduated quotas
• 7B EigenTrust: Sybil-resistant global trust propagation
• 7C Content Defense: Quality scoring, MinHash/LSH similarity, quarantine store, admin API
• 7D Circuit Breakers: Per-agent banning with Closed/Open/HalfOpen state machine

Test Coverage (Verified)

Area	Tests	Status
Circuit Breakers (7D)	25	PASS
Trust Graph Store (7B)	23	PASS
Trust Rank Store	22	PASS
PoW types (7A)	19	PASS
Domain Trust Store (7B)	18	PASS
Admission Store (7A)	16	PASS
Content Defense (quality) (7C)	13	PASS
Similarity Index (MinHash/LSH) (7C)	12	PASS
Quarantine Store (7C)	9	PASS
Trust Tier types (7A)	8	PASS
API Admission integration	6	PASS
Content Defense Layer (7C)	5	PASS
Total Phase 7	176	ALL PASS

Realistic Usage Scenarios

Scenario 1: New Agent Onboarding

Goal: Verify graduated difficulty protects against spam bots while not blocking legitimate agents.

# 1. New agent with no history should require PoW
curl -X GET http://localhost:18180/v1/admission/status \
  -H "X-Agent-Id: 0000000000000000000000000000000000000000000000000000000000000001"
# Expected: 200 with pow_required: true, difficulty: 16

# 2. Submit first assertions with PoW proof
# Agent must solve: BLAKE3(nonce || agent_id || timestamp) has 16 leading zero bits
# This takes ~16 seconds on average

# 3. After 10 assertions, difficulty drops to 1 bit (trivial)
# 4. After 50 assertions OR trust > 0.6, PoW exempt

Acceptance Criteria:

• New agents see pow_required: true, difficulty: 16
• HTTP 428 returned when PoW missing/invalid
• Difficulty graduates: 16 bits (1-10) → 1 bit (11-50) → 0 (51+)
• Trusted agents (>0.6) are exempt regardless of assertion count

Scenario 2: Trust Tier Quotas

Goal: Verify rate limiting scales with trust level.

Tier	Trust Range	Quota Multiplier	Hourly Limit
Untrusted	0.0-0.3	0.1x	1,000/hr
Limited	0.3-0.5	0.5x	5,000/hr
Verified	0.5-0.7	1.0x	10,000/hr
Trusted	0.7-0.9	2.0x	20,000/hr
Authority	0.9-1.0	10.0x	100,000/hr

Acceptance Criteria:

• Quota headers present in responses (X-RateLimit-*)
• Untrusted agents limited to 0.1x base quota
• Authority agents get 10x quota
• HTTP 429 returned when quota exceeded

Scenario 3: EigenTrust Sybil Resistance

Goal: Verify isolated trust rings get near-zero global trust.

Legitimate Network:          Sybil Ring:
   Seed ─────> A              X ──> Y
     │         │              │     │
     v         v              v     v
     B ──────> C              Z <── W

Acceptance Criteria:

• Seed-connected agents (A, B, C) accumulate positive global trust
• Isolated ring (X, Y, Z, W) converges to near-zero trust
• Power iteration converges in <100 iterations (ε = 1e-4)
• Domain-specific trust factors applied correctly

Scenario 4: Content Quality Filtering

Goal: Verify spam/noise detection without blocking legitimate content.

Content Type	Expected Quality	Should Quarantine?
Normal assertion: "Aspirin:treats:Headache"	>0.6	No
Low entropy: "aaaa:bbbb:cccc"	<0.4	Yes
Structured data with JSON	>0.7 (bonus)	No
Untrusted agent + high confidence	<0.5 (penalty)	Yes

Acceptance Criteria:

• Shannon entropy check flags random noise (< 1.5 bits/char)
• Minimum subject/predicate length enforced (default 3 chars)
• Structured data (JSON, URLs, dates) gets +0.1 bonus
• Untrusted + high confidence gets -0.5 penalty
• Quality < 0.4 triggers quarantine

Scenario 5: Quarantine Admin Workflow

Goal: Verify suspicious content can be reviewed and processed.

# 1. List pending quarantine events
curl http://localhost:18180/v1/admin/quarantine?limit=20

# 2. Review specific event
curl http://localhost:18180/v1/admin/quarantine/{hash}

# 3. Approve or reject
curl -X POST http://localhost:18180/v1/admin/quarantine/{hash}/approve
curl -X POST http://localhost:18180/v1/admin/quarantine/{hash}/reject

Acceptance Criteria:

• GET /v1/admin/quarantine lists pending events with reasons
• GET /v1/admin/quarantine/{hash} returns full assertion bytes
• POST .../approve moves assertion to main index
• POST .../reject marks as reviewed but keeps quarantined
• Quarantine reasons clearly indicate why flagged

Integration Points to Verify

1. Ingestion Pipeline Integration

   • Content defense layer called before indexing
   • Quarantine bypasses normal index path
   • Bloom filter restored on restart

2. Trust Store Interplay

   • EigenTrust feeds into TrustTier calculation
   • Domain trust factors into Authority lens weights
   • Trust decay applies to computed scores

3. API Middleware Chain

   • AdmissionLayer checks PoW before rate limiting
   • MeterLayer applies tier-based quotas
   • Headers reflect current trust state

Scenario 6: Near-Duplicate Detection (MinHash/LSH)

Goal: Verify similar content is flagged without blocking unique assertions.

Content Pair	Jaccard Similarity	Expected
"Aspirin:treats:Headache" vs same	1.0	Duplicate
"Aspirin:treats:Headache" vs "Aspirin:treats:Migraine"	~0.7	Unique
"Aspirin treats headaches" vs "Aspirin:treats:Headache"	~0.85	Unique
"Asprin:treats:Headach" (typos) vs "Aspirin:treats:Headache"	~0.92	Duplicate

Acceptance Criteria:

• Bloom filter provides fast "definitely not seen" path
• MinHash signatures (k=128) computed correctly
• LSH bands (16 bands × 8 rows) enable efficient lookup
• Jaccard threshold of 0.9 correctly identifies near-duplicates
• Unique content with similar structure passes through

Scenario 7: Circuit Breaker State Machine (7D)

Goal: Verify misbehaving agents are temporarily banned with recovery path.

State Flow:
CLOSED (normal) --[5 failures]--> OPEN (banned)
OPEN --[30 sec timeout]--> HALF_OPEN (testing)
HALF_OPEN --[1 success]--> CLOSED
HALF_OPEN --[1 failure]--> OPEN

Acceptance Criteria:

• New agents start with no circuit record (allowed)
• 5 failures within window trips circuit to OPEN
• OPEN agents receive HTTP 503 with Retry-After header
• After 30 sec, OPEN transitions to HALF_OPEN
• Single success in HALF_OPEN closes circuit
• Single failure in HALF_OPEN re-trips to OPEN
• Admin can manually reset circuits

Known Limitations

1. Performance Untested:
   • EigenTrust computation on large graphs (>10k agents)
   • Bloom filter memory at scale (currently sized for 1M items)
   • Quarantine store scan performance with many pending items
   • Circuit breaker store with many tripped agents

Commands to Run

# Full test suite
cargo test --workspace

# Phase 7 specific tests (176 total)
cargo test -p stemedb-storage -- circuit_breaker    # 7D: 25 tests
cargo test -p stemedb-storage -- trust_graph        # 7B: 23 tests
cargo test -p stemedb-storage -- trust_rank         # Trust: 22 tests
cargo test -p stemedb-core -- pow                   # 7A: 19 tests
cargo test -p stemedb-storage -- domain_trust       # 7B: 18 tests
cargo test -p stemedb-storage -- admission          # 7A: 16 tests
cargo test -p stemedb-storage -- content_defense    # 7C: 13 tests
cargo test -p stemedb-storage -- similarity_index   # 7C: 12 tests
cargo test -p stemedb-storage -- quarantine         # 7C: 9 tests
cargo test -p stemedb-core -- trust_tier            # 7A: 8 tests
cargo test -p stemedb-api --test admission_integration  # API: 6 tests
cargo test -p stemedb-ingest -- content_defense     # 7C: 5 tests

# Clippy must pass
cargo clippy --workspace -- -D warnings

# Go SDK
cd sdk/go/steme && go test -v

Success Criteria

Phase 7 UAT passes when:

1. All 176 Phase 7 tests pass
2. All 7 usage scenarios verified manually
3. Clippy clean with no warnings
4. Go SDK tests pass
5. API endpoints return correct responses
6. Quarantine workflow complete end-to-end
7. Circuit breaker state transitions verified
8. Near-duplicate detection at 0.9 Jaccard threshold works

Related Documentation

• Admission Control API
• Phase 6 UAT
• Roadmap Phase 7