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

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
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`:
  ```sql
  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
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #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
<!-- AC:END -->
