feat(analysis): add recurring pattern detection for governance events

[fagemx]

Context

Morning summary（fagemx/thyra#224）需要查 Edda 發現重複出現的問題。例如：「Safety Chief 已經連續 3 天 rollback 活動獎勵，根因可能是 Event Chief 設定過高」。

What Needs to Happen

• 分析 API：GET /api/patterns?village_id=xxx&lookback_days=7
• 偵測：同類型 decision 重複出現（>= 3 次 within window）
• 偵測：同 chief 連續相同 action
• 偵測：rollback 頻率上升趨勢
• 回傳：pattern description + 出現次數 + 時間分布
• Phase 1 可用簡單 SQL 聚合
• Phase 2 可用 LLM 做更深度分析

References

• Cross-repo: feat(market): summary generator queries Edda for historical insights thyra#224 (summary queries for insights)
• Cross-repo: feat(chief): query Edda precedents before making decisions thyra#222 (chiefs can also query patterns)

---

Midnight Market: from logbook to intelligence

[fagemx]

Research Phase: Recurring Pattern Detection for Governance Events (GH-318)

1. Problem Statement

Thyra's morning summary (fagemx/thyra#224) needs to query Edda for recurring patterns in governance decisions. Example: "Safety Chief has rolled back activity rewards 3 days in a row -- root cause may be Event Chief setting rewards too high."

The feature requires a new API endpoint: GET /api/patterns?village_id=xxx&lookback_days=7 that detects:

1. Same decision type recurring >= 3 times within a window
2. Same chief performing the same action repeatedly
3. Rollback frequency trending upward

2. Codebase Analysis

2.1 Data Model: decisions Table

File: crates/edda-ledger/src/sqlite_store.rs:52-66

The decisions table stores:

• key / value / reason / domain -- the decision itself
• supersedes_id -- links to previous decision it replaces (rollback chain)
• authority -- "human", "agent", "system" (maps to "chief" concept)
• village_id -- village scope identifier (added in v11)
• status -- "proposed", "active", "experimental", "deprecated", "superseded"

Key insight: supersedes_id creates a chain showing when decisions are overridden (rollback). The authority field maps to which "chief" made the decision.

2.2 Existing Village Stats (GH-316, merged)

File: crates/edda-ledger/src/sqlite_store.rs:1895-2022

village_stats() already computes:

• Total decisions, by_status, by_authority
• Top domains (GROUP BY domain)
• Daily trend (GROUP BY DATE(ts))
• Rollback rate (superseded / total)

This is pure aggregation. Pattern detection needs temporal sequence analysis, not just counts.

2.3 Telemetry Stats Pattern (GH-317, merged)

File: crates/edda-serve/src/lib.rs:1999-2155

GET /api/telemetry/stats shows the pattern for time-windowed analysis:

1. Compute after date from lookback_days
2. Query events within window
3. In-memory aggregation
4. Return JSON

This is the closest existing pattern to what we need.

2.4 Decision Query Infrastructure

• active_decisions() -- supports temporal filtering, domain filtering
• decision_timeline(key) -- all versions of a single key (active + superseded)
• domain_timeline(domain) -- all decisions for a domain

2.5 Architecture Decision: Where to Put the Logic

Recommendation: SQL queries in edda-ledger::sqlite_store (following village_stats pattern), HTTP handler in edda-serve. This matches the existing pattern: data access in ledger, HTTP in serve.

3. SQL Queries for Phase 1

Three queries needed, all using GROUP BY on indexed columns:

1. Recurring decisions: GROUP BY key, domain WHERE count >= min_occurrences
2. Chief repeated actions: GROUP BY authority, key WHERE count >= min_occurrences
3. Rollback trends: WHERE supersedes_id IS NOT NULL, GROUP BY key, count >= 2

4. Constraints

• No new crate needed (Phase 1 is simple SQL aggregation)
• No external dependencies (pure SQL + Rust)
• Must be scoped to village_id (Thyra queries by village)
• The decisions.village_id column has an index (idx_decisions_village)

[fagemx]

Innovation Phase: Recurring Pattern Detection (GH-318)

Approach Evaluation

Option A: Pure SQL Aggregation in edda-ledger (Chosen)

• Follows existing village_stats() pattern exactly
• SQL GROUP BY is efficient on indexed columns
• Single database round-trip per pattern type
• Zero new dependencies
• Best fit for Phase 1

Option B: Ledger Query + Rust In-Memory Analysis

• More flexible (sliding windows, trend slopes, sequence analysis)
• Loads more data into memory
• Better for Phase 2 when LLM analysis is added

Option C: New edda-analysis Crate

• Clean separation but over-engineering for Phase 1
• YAGNI: only one consumer (serve endpoint) for now
• Premature

Design Details

Types

pub enum PatternType {
    RecurringDecision,     // same key changed >= N times
    ChiefRepeatedAction,   // same authority+key >= N times
    RollbackTrend,         // supersession chain >= 2 times
}

pub struct DetectedPattern {
    pub pattern_type: PatternType,
    pub key: String,
    pub domain: String,
    pub authority: Option<String>,
    pub occurrences: usize,
    pub first_seen: String,
    pub last_seen: String,
    pub dates: Vec<String>,
    pub description: String,
    pub trending_up: Option<bool>,  // for rollback patterns
}

Trend Detection

For "rollback frequency rising": compare rollback count in first half vs second half of the window. If second half > first half, flag as trending_up.

Deduplication

A single key might match both "recurring_decision" and "rollback_trend". Response includes both -- each provides different insight. Consumer (Thyra) prioritizes.

Edge Cases

1. No village_id -> 400 validation error
2. Village with no decisions -> empty patterns array
3. lookback_days capped at 90 to prevent expensive queries
4. authority NULL -> skip for chief patterns (filter authority != 'system')

[fagemx]

Implementation Plan: Recurring Pattern Detection (GH-318)

Summary

Add GET /api/patterns endpoint to detect recurring governance patterns within a village's decisions. Phase 1 uses SQL aggregation; no new crates or dependencies needed.

Files Changed

File	Change	Lines (est.)
crates/edda-ledger/src/sqlite_store.rs	Add detect_village_patterns() + types	~200
crates/edda-serve/src/lib.rs	Add route + handler + tests	~250

Step 1: Add Pattern Types to edda-ledger

Location: After VillageStatsPeriod struct (~line 287 in sqlite_store.rs)

#[derive(Debug, Clone, serde::Serialize)]
#[serde(rename_all = "snake_case")]
pub enum PatternType {
    RecurringDecision,
    ChiefRepeatedAction,
    RollbackTrend,
}

#[derive(Debug, Clone, serde::Serialize)]
pub struct DetectedPattern {
    pub pattern_type: PatternType,
    pub key: String,
    pub domain: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub authority: Option<String>,
    pub occurrences: usize,
    pub first_seen: String,
    pub last_seen: String,
    pub dates: Vec<String>,
    pub description: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub trending_up: Option<bool>,
}

#[derive(Debug, Clone, serde::Serialize)]
pub struct PatternDetectionResult {
    pub village_id: String,
    pub lookback_days: u32,
    pub after: String,
    pub patterns: Vec<DetectedPattern>,
    pub total_patterns: usize,
}

Step 2: Add detect_village_patterns() to Ledger

Location: After village_stats() method (~line 2022)

Method signature:

pub fn detect_village_patterns(
    &self,
    village_id: &str,
    after: &str,
    min_occurrences: usize,
) -> anyhow::Result<Vec<DetectedPattern>>

Three SQL queries:

Query 1 - Recurring Decisions: GROUP BY key, domain WHERE village_id and ts >= after, HAVING COUNT >= min_occurrences

Query 2 - Chief Repeated Actions: GROUP BY authority, key WHERE authority != 'system', HAVING COUNT >= min_occurrences

Query 3 - Rollback Trends: WHERE supersedes_id IS NOT NULL, GROUP BY key, domain, HAVING COUNT >= 2

Trend detection: split dates at window midpoint, flag trending_up = true if second half has more rollbacks.

Step 3: Add HTTP Route and Handler

Location: After /api/villages/{village_id}/stats route in edda-serve

Route: .route("/api/patterns", get(get_patterns))

Query params:

• village_id (required)
• lookback_days (default 7, max 90)
• min_occurrences (default 3)

Handler computes after timestamp from lookback_days (same as telemetry/stats), calls ledger method, wraps in PatternDetectionResult.

Step 4: Tests

Ledger Tests (sqlite_store.rs)

• test_detect_village_patterns_recurring: 5 decisions same key -> detected
• test_detect_village_patterns_chief_repeated: 3 decisions same authority+key -> detected
• test_detect_village_patterns_rollback: supersession chain -> detected with trending_up
• test_detect_village_patterns_below_threshold: 2 decisions with threshold 3 -> not detected
• test_detect_village_patterns_empty_village: empty result

HTTP Tests (serve lib.rs)

• test_get_patterns_endpoint: POST decisions, GET /api/patterns, verify shape
• test_get_patterns_missing_village_id: verify 400

API Contract

Request

GET /api/patterns?village_id=village_abc&lookback_days=7&min_occurrences=3

Response (200 OK)

{
  "village_id": "village_abc",
  "lookback_days": 7,
  "after": "2026-03-20T00:00:00Z",
  "total_patterns": 3,
  "patterns": [
    {
      "pattern_type": "recurring_decision",
      "key": "rewards.daily_limit",
      "domain": "economy",
      "authority": "event_chief",
      "occurrences": 5,
      "first_seen": "...",
      "last_seen": "...",
      "dates": ["2026-03-20", "2026-03-21", ...],
      "description": "rewards.daily_limit changed 5 times in 7 days"
    }
  ]
}

Verification

cargo fmt --check
cargo clippy --workspace --all-targets
cargo test -p edda-ledger test_detect_village_patterns
cargo test -p edda-serve test_get_patterns
cargo test --workspace

Non-Goals (Phase 2)

• LLM-powered deeper analysis
• Cross-village pattern correlation
• Caching / materialized pattern views
• Pattern notification/alerting

[fagemx]

Work completed. PR created: #371

Implementation adds GET /api/patterns endpoint with three pattern detection types (recurring_decision, chief_repeated_action, rollback_trend). All 7 new tests passing, clippy clean.