Update Quota Tracking (#301)

Replaces the old QuotaWindow[]-based system with a flat Meter[] model
where each meter is self-describing with kind, unit, period fields, and
status — eliminating per-checker UI switches, checker-level categories,
compound enum window types, and 21 near-duplicate display components.

Backend changes:
- New Meter/MeterCheckResult types in src/types/meter.ts
- Self-registering checker-registry.ts (defineChecker + loadAllCheckers)
- New meter_snapshots table schema (SQLite + PostgreSQL)
- All 22 checkers rewritten to export default defineChecker({...})
- apertis and apertis-coding-plan merged into single apertis checker
- quota-scheduler.ts rewired to use registry + persist to
meter_snapshots
- /v0/management/quotas routes return MeterCheckResult shape
- apertis-coding-plan removed from config schema

Frontend changes:
- New QuotaCheckerInfo type with meters: Meter[] replacing latest:
snapshot[]
- New generic components: BalanceMeterRow, AllowanceMeterRow, MeterValue
- checker-presentation.ts for display names
- Quotas.tsx, CombinedBalancesCard, CompactQuotasCard,
CompactBalancesCard
  rewritten to use meters array directly
- Sidebar.tsx updated to derive balance/allowance from meter kinds
- All 21 XxxQuotaDisplay.tsx components deleted
- QuotaHistoryModal, BalanceHistoryModal deleted
- api.ts updated to use new response shape

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: mcowger

README.md

@@ -211,6 +211,69 @@ On first startup with `ENCRYPTION_KEY` set, existing plaintext values are automa
 
 ---
 
+## Admin CLI Utilities
+
+Plexus ships several one-shot CLI subcommands for database maintenance tasks. Pass the subcommand name as the first argument to the binary (or `bun run src/index.ts`).
+
+### Rotate Encryption Key (`rekey`)
+
+Decrypts all sensitive fields with the current key and re-encrypts them with a new one. Run this before rotating `ENCRYPTION_KEY` in your environment.
+
+```bash
+# Docker
+docker run --rm \
+  -e DATABASE_URL=sqlite:///app/data/plexus.db \
+  -e ENCRYPTION_KEY="<current-key>" \
+  -e NEW_ENCRYPTION_KEY="<new-key>" \
+  -v plexus-data:/app/data \
+  ghcr.io/mcowger/plexus:latest rekey
+
+# Binary
+ENCRYPTION_KEY="<current-key>" NEW_ENCRYPTION_KEY="<new-key>" \
+  DATABASE_URL=sqlite://./data/plexus.db ./plexus rekey
+```
+
+After a successful run, update `ENCRYPTION_KEY` to the new value before restarting the server.
+
+→ See [Configuration: Encryption](docs/CONFIGURATION.md#encryption-at-rest-optional)
+
+### Migrate Quota Snapshots (`migrate-quota-snapshots`)
+
+One-time ETL that copies historical data from the legacy `quota_snapshots` table into the new `meter_snapshots` table introduced in the quota-tracking overhaul. Run this once after upgrading to a version that includes the new quota system.
+
+```bash
+# Docker
+docker run --rm \
+  -e DATABASE_URL=sqlite:///app/data/plexus.db \
+  -v plexus-data:/app/data \
+  ghcr.io/mcowger/plexus:latest migrate-quota-snapshots
+
+# Binary
+DATABASE_URL=sqlite://./data/plexus.db ./plexus migrate-quota-snapshots
+
+# Development
+DATABASE_URL=sqlite://./data/plexus.db bun run src/index.ts migrate-quota-snapshots
+```
+
+`DATABASE_URL` must be set explicitly — there is no default. The command is **idempotent**: rows that already exist in `meter_snapshots` are skipped, so it is safe to run more than once. If `quota_snapshots` does not exist or is empty the command exits cleanly with no changes.
+
+**Field mapping summary:**
+
+| `quota_snapshots` | `meter_snapshots` | Notes |
+|---|---|---|
+| `provider` | `provider` | direct |
+| `checker_id` | `checker_id` | direct |
+| `group_id` | `group` | renamed |
+| `window_type` | `meter_key` | used as-is |
+| `window_type` | `kind` / `period_*` | `daily`→allowance/day, `monthly`→allowance/month, `balance`→balance, etc. |
+| `description` | `label` | falls back to `window_type` if null |
+| `unit` | `unit` | defaults to `''` if null |
+| `status` | `status` | defaults to `'ok'` if null |
+| `utilization_percent` | `utilization_percent` + `utilization_state` | null→`unknown`, number→`reported` |
+| *(not present)* | `checker_type` | set to `'unknown'` |
+
+---
+
 ## License
 
 MIT License — see [LICENSE](LICENSE) file

packages/backend/drizzle/schema/index.ts

@@ -1,4 +1,5 @@
 // Re-export from sqlite by default for backward compatibility
+export * from './sqlite/meter-snapshots';
 export * from './sqlite/request-usage';
 export * from './sqlite/provider-cooldowns';
 export * from './sqlite/debug-logs';
@@ -21,6 +22,7 @@ export { debugLogs as pgDebugLogs } from './postgres/debug-logs';
 export { inferenceErrors as pgInferenceErrors } from './postgres/inference-errors';
 export { providerPerformance as pgProviderPerformance } from './postgres/provider-performance';
 export { quotaSnapshots as pgQuotaSnapshots } from './postgres/quota-snapshots';
+export { meterSnapshots as pgMeterSnapshots } from './postgres/meter-snapshots';
 export {
   responses as pgResponses,
   conversations as pgConversations,

packages/backend/drizzle/schema/postgres/index.ts

@@ -1,3 +1,4 @@
+export * from './meter-snapshots';
 export * from './request-usage';
 export * from './provider-cooldowns';
 export * from './debug-logs';

packages/backend/drizzle/schema/postgres/meter-snapshots.ts

@@ -0,0 +1,40 @@
+import { pgTable, serial, text, real, integer, bigint, index } from 'drizzle-orm/pg-core';
+
+export const meterSnapshots = pgTable(
+  'meter_snapshots',
+  {
+    id: serial('id').primaryKey(),
+    checkerId: text('checker_id').notNull(),
+    checkerType: text('checker_type').notNull(),
+    provider: text('provider').notNull(),
+    meterKey: text('meter_key').notNull(),
+    kind: text('kind').notNull(), // 'balance' | 'allowance'
+    unit: text('unit').notNull(),
+    label: text('label').notNull(),
+    group: text('group'),
+    scope: text('scope'),
+    limit: real('limit'),
+    used: real('used'),
+    remaining: real('remaining'),
+    utilizationState: text('utilization_state').notNull(), // 'reported' | 'unknown' | 'not_applicable'
+    utilizationPercent: real('utilization_percent'),
+    status: text('status').notNull(),
+    periodValue: integer('period_value'),
+    periodUnit: text('period_unit'),
+    periodCycle: text('period_cycle'),
+    resetsAt: bigint('resets_at', { mode: 'number' }),
+    success: integer('success').notNull().default(1),
+    errorMessage: text('error_message'),
+    checkedAt: bigint('checked_at', { mode: 'number' }).notNull(),
+    createdAt: bigint('created_at', { mode: 'number' }).notNull(),
+  },
+  (table) => ({
+    checkerMeterCheckedIdx: index('idx_meter_checker_meter_checked').on(
+      table.checkerId,
+      table.meterKey,
+      table.checkedAt
+    ),
+    providerCheckedIdx: index('idx_meter_provider_checked').on(table.provider, table.checkedAt),
+    checkedAtIdx: index('idx_meter_checked_at').on(table.checkedAt),
+  })
+);

packages/backend/drizzle/schema/sqlite/index.ts

@@ -1,3 +1,4 @@
+export * from './meter-snapshots';
 export * from './request-usage';
 export * from './provider-cooldowns';
 export * from './debug-logs';

packages/backend/drizzle/schema/sqlite/meter-snapshots.ts

@@ -0,0 +1,40 @@
+import { sqliteTable, integer, text, real, index } from 'drizzle-orm/sqlite-core';
+
+export const meterSnapshots = sqliteTable(
+  'meter_snapshots',
+  {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    checkerId: text('checker_id').notNull(),
+    checkerType: text('checker_type').notNull(),
+    provider: text('provider').notNull(),
+    meterKey: text('meter_key').notNull(),
+    kind: text('kind').notNull(), // 'balance' | 'allowance'
+    unit: text('unit').notNull(),
+    label: text('label').notNull(),
+    group: text('group'),
+    scope: text('scope'),
+    limit: real('limit'),
+    used: real('used'),
+    remaining: real('remaining'),
+    utilizationState: text('utilization_state').notNull(), // 'reported' | 'unknown' | 'not_applicable'
+    utilizationPercent: real('utilization_percent'),
+    status: text('status').notNull(),
+    periodValue: integer('period_value'),
+    periodUnit: text('period_unit'),
+    periodCycle: text('period_cycle'),
+    resetsAt: integer('resets_at', { mode: 'timestamp_ms' }),
+    success: integer('success', { mode: 'boolean' }).notNull().default(true),
+    errorMessage: text('error_message'),
+    checkedAt: integer('checked_at', { mode: 'timestamp_ms' }).notNull(),
+    createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  },
+  (table) => ({
+    checkerMeterCheckedIdx: index('idx_meter_checker_meter_checked').on(
+      table.checkerId,
+      table.meterKey,
+      table.checkedAt
+    ),
+    providerCheckedIdx: index('idx_meter_provider_checked').on(table.provider, table.checkedAt),
+    checkedAtIdx: index('idx_meter_checked_at').on(table.checkedAt),
+  })
+);

packages/backend/src/cli/migrate-quota-snapshots.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env bun
+/**
+ * One-time ETL: migrate data from the legacy `quota_snapshots` table to the
+ * new `meter_snapshots` table introduced in the quota-tracking overhaul.
+ *
+ * Usage:
+ *   bun run src/cli/migrate-quota-snapshots.ts
+ *
+ * The DATABASE_URL env var must be set explicitly — there is no default fallback.
+ *
+ * This script is idempotent — rows already present in `meter_snapshots` for
+ * a given (checkerId, meterKey, checkedAt) triplet are skipped, so it is safe
+ * to run more than once.
+ *
+ * Field mapping from quota_snapshots → meter_snapshots:
+ *   provider        → provider
+ *   checker_id      → checker_id       (checkerId)
+ *   group_id        → group            (renamed)
+ *   window_type     → kind, period*    (derived – see mapWindowType)
+ *   window_type     → meter_key        (used as a stable key)
+ *   description     → label            (falls back to window_type)
+ *   checked_at      → checked_at
+ *   limit           → limit
+ *   used            → used
+ *   remaining       → remaining
+ *   utilization_%   → utilization_percent + utilization_state
+ *   unit            → unit             (defaults to '' if null)
+ *   resets_at       → resets_at
+ *   status          → status           (defaults to 'ok' if null)
+ *   success         → success
+ *   error_message   → error_message
+ *   created_at      → created_at
+ *
+ *   checker_type    → 'unknown'        (not stored in old table)
+ */
+
+import { initializeDatabase } from '../db/client';
+import { runMigrations } from '../db/migrate';
+import { logger } from '../utils/logger';
+import { migrateLegacySnapshots } from '../services/quota/legacy-snapshot-migrator';
+
+async function main() {
+  if (!process.env.DATABASE_URL) {
+    logger.error('DATABASE_URL must be set');
+    process.exit(1);
+  }
+
+  initializeDatabase();
+  await runMigrations();
+
+  const { inserted, skipped, totalSource } = await migrateLegacySnapshots();
+
+  if (totalSource === 0) {
+    logger.info('Nothing to migrate.');
+  } else {
+    logger.info(`Migration complete. Inserted: ${inserted}, Skipped: ${skipped}`);
+  }
+}
+
+export { main as migrateQuotaSnapshotsMain };
+
+if (import.meta.main) {
+  main().catch((err) => {
+    logger.error('Quota snapshot migration failed:', err);
+    process.exit(1);
+  });
+}

packages/backend/src/config.ts

@@ -301,13 +301,6 @@ const ProviderQuotaCheckerSchema = z.discriminatedUnion('type', [
     id: z.string().trim().min(1).optional(),
     options: ApertisQuotaCheckerOptionsSchema.optional().default({}),
   }),
-  z.object({
-    type: z.literal('apertis-coding-plan'),
-    enabled: z.boolean().default(true),
-    intervalMinutes: z.number().min(1).default(30),
-    id: z.string().trim().min(1).optional(),
-    options: ApertisQuotaCheckerOptionsSchema.optional().default({}),
-  }),
   z.object({
     type: z.literal('minimax-coding'),
     enabled: z.boolean().default(true),
@@ -905,7 +898,6 @@ export const VALID_QUOTA_CHECKER_TYPES = [
   'copilot',
   'wisdomgate',
   'apertis',
-  'apertis-coding-plan',
   'poe',
   'gemini-cli',
   'antigravity',

packages/backend/src/db/types.ts

@@ -6,7 +6,8 @@ export type ProviderCooldown = InferSelectModel<typeof schema.providerCooldowns>
 export type DebugLog = InferSelectModel<typeof schema.debugLogs>;
 export type InferenceError = InferSelectModel<typeof schema.inferenceErrors>;
 export type ProviderPerformance = InferSelectModel<typeof schema.providerPerformance>;
-export type QuotaSnapshot = InferSelectModel<typeof schema.quotaSnapshots>;
+// QuotaSnapshot / NewQuotaSnapshot removed — the old quota_snapshots table is
+// superseded by meter_snapshots. See src/types/meter.ts for the new types.
 export type McpRequestUsage = InferSelectModel<typeof schema.mcpRequestUsage>;
 export type McpDebugLog = InferSelectModel<typeof schema.mcpDebugLogs>;
 
@@ -15,7 +16,6 @@ export type NewProviderCooldown = InferInsertModel<typeof schema.providerCooldow
 export type NewDebugLog = InferInsertModel<typeof schema.debugLogs>;
 export type NewInferenceError = InferInsertModel<typeof schema.inferenceErrors>;
 export type NewProviderPerformance = InferInsertModel<typeof schema.providerPerformance>;
-export type NewQuotaSnapshot = InferInsertModel<typeof schema.quotaSnapshots>;
 export type NewMcpRequestUsage = InferInsertModel<typeof schema.mcpRequestUsage>;
 export type NewMcpDebugLog = InferInsertModel<typeof schema.mcpDebugLogs>;
 

packages/backend/src/index.ts

@@ -13,6 +13,17 @@ if (subcommand === 'rekey') {
   await new Promise(() => {}); // Block forever; process.exit above will terminate
 }
 
+if (subcommand === 'migrate-quota-snapshots') {
+  const { migrateQuotaSnapshotsMain } = await import('./cli/migrate-quota-snapshots');
+  migrateQuotaSnapshotsMain()
+    .then(() => process.exit(0))
+    .catch((err) => {
+      console.error('Quota snapshot migration failed:', err);
+      process.exit(1);
+    });
+  await new Promise(() => {});
+}
+
 import Fastify, { FastifyReply, FastifyRequest } from 'fastify';
 import cors from '@fastify/cors';
 import multipart from '@fastify/multipart';