rspace-online/backlog/tasks/task-149 - Power-index-time-series-snapshots.md

id	title	status	assignee	created_date	labels	dependencies	references	priority
TASK-149	Power index time-series snapshots	To Do		2026-04-16 18:56	governance analytics power-indices	TASK-144	src/encryptid/schema.sql src/encryptid/power-indices.ts modules/rnetwork/components/folk-graph-viewer.ts	low

Description

Store daily snapshots of power concentration metrics for trend analysis.

What

Currently power_indices table overwrites on each 5-min cycle. Add a power_snapshots table that stores one row per space+authority per day with aggregate metrics. Enables "is power becoming more or less concentrated over time?" analysis.

Primitive: Daily Snapshot Aggregation

• New table power_snapshots:

  CREATE TABLE power_snapshots (
    space_slug TEXT NOT NULL,
    authority TEXT NOT NULL,
    snapshot_date DATE NOT NULL,
    player_count INTEGER,
    gini_coefficient REAL,
    herfindahl_index REAL,
    top3_banzhaf_sum REAL,
    effective_voters REAL,
    PRIMARY KEY (space_slug, authority, snapshot_date)
  );
  

• In trust engine cycle: after computing power indices, check if today's snapshot exists. If not, insert.
• One INSERT per space+authority per day — negligible DB cost.

Frontend: Sparkline in power panel

• folk-graph-viewer.ts power panel: fetch GET /api/power-snapshots?space=X&authority=Y&days=30
• Render 30-day sparkline of Gini + HHI below the gauge metrics
• Red trend line = concentrating, green = dispersing

Implementation

• src/encryptid/schema.sql: New table
• src/encryptid/db.ts: upsertPowerSnapshot(), getPowerSnapshots(space, authority, days)
• src/encryptid/power-indices.ts: snapshotIfNeeded() called from trust engine
• src/encryptid/server.ts: GET /api/power-snapshots endpoint
• folk-graph-viewer.ts: 30-day sparkline SVG in power panel
• ~80 lines backend, ~40 lines frontend

Acceptance Criteria

• #1 power_snapshots table with daily aggregates per space+authority
• #2 Auto-insert one snapshot per day during trust engine cycle
• #3 API endpoint returns N days of historical snapshots
• #4 30-day sparkline in power panel showing Gini + HHI trend
• #5 Red/green trend coloring based on direction