feat(monitoring,costs,quota): Monitoring reorg + Costs section + Quota Share Engine (planos 16+22) by diegosouzapw · Pull Request #2859 · cheaper-inference/OmniRoute

diegosouzapw · 2026-05-28T13:59:19Z

Summary

Grupo B do refactorpages v3.8.6 — entrega consolidada de 2 planos:

Plano 16 (Monitoring reorg + Costs section): reorganiza Monitoring em 3 subgrupos (Logs/Audit/System), nova seção de nível 1 Costs (Overview/Pricing/Budget/QuotaShare), Activity diferenciado de Audit Log (timeline amigável vs tabela compliance), AuditLogTab.tsx deletado (duplicata confirmada), CompressionLogTab namespace fix (settings → logs), /api/compliance/audit-log ganha ?level=high|all.
Plano 22 (Quota Share Engine): pools persistidos em DB (sai do localStorage), rastreamento real por API key, enforcement no caminho quente (chatCore.ts PRE/POST hook + combo.ts soft penalty), algoritmo fair-share work-conserving multi-dimensional (% / requests / tokens / $) com Sliding Window Counter 2-bucket, drivers SQLite (default) + Redis (opcional), 13 endpoints REST, UI redesign + página de Plans (override por provider).

10 frentes paralelas executadas e mergeadas

Frente	Escopo	Commits
F1	Shared foundation: types/Zod schemas/audit allowlist/planRegistry/activityIcons	5
F2	DB migrations 073/074/075 + módulos (`quotaPools`, `quotaConsumption`, `providerPlans`) + `localDb` re-exports	7
F3	Sidebar reorg (Monitoring 3-groups + Costs section) + i18n PT-BR/EN	3
F6	QuotaStore core: SQLite + Redis + fairShare + planResolver + burnRate + saturationSignals	11
F4	Activity page (`/dashboard/activity`) + audit-log `?level=high` filter + delete AuditLogTab	7
F5	ComplianceTab actor filter + CompressionLogTab namespace fix + usage audit report	4
F7	Enforce wiring (chatCore PRE/POST hook + combo `QUOTA_SOFT_DEPRIORITIZE_FACTOR` + spendRecorder)	5
F8	13 REST endpoints `/api/quota/**` + `/api/settings/quota-store` + 6 integration test files	5
F9	UI quota-share refactor (LS→DB migration hook) + Plans page + 7 components + 3 hooks + 6 vitest UI tests + sidebar `costs-quota-plans`	7
F10	Audit Hard Rules + docs (`QUOTA_SHARE.md`, `MONITORING_SECTIONS.md`) + REPOSITORY_MAP + openapi.yaml + 4 E2E specs + `audit-report-B.md`	7

Métricas

72 commits, 164 files changed, +14.3k/-2.5k LOC
86 tests passing (55 integration + 31 vitest UI + sidebar/audit/db tests)
Coverage gate: 40/40/40/40 — PASS (medido: St 62% / Br 69% / Fn 60% / Ln 62%)
Lint: 0 errors · Typecheck core + noimplicit:core: clean · Cycles: 0 new

Hard Rules audit (Group B branch — F10 grep-based)

Rule	Status	Evidência
#1 Secrets	✅	0 hits
#3 eval/new Function	✅	1 false positive em interface TypeScript de Redis (`redisQuotaStore.ts:39` — método nominal, não invocação)
#5 raw SQL fora de `src/lib/db/`	✅	0 hits
#12 `err.stack`/`err.message` raw em response body	✅	0 hits (todas as rotas usam `buildErrorBody`)
#15/#17 LOCAL_ONLY enforcement	✅	`/api/quota/**` e `/api/settings/quota-store` NÃO em `LOCAL_ONLY_API_PREFIXES` (correto per B18 — não spawnam processos)
#16 Co-Authored-By	✅	0 hits em todos os 72 commits
#10 --no-verify	✅	0 hits
#7 Zod validation	✅	Todas as rotas com Zod schemas em `src/shared/schemas/quota.ts`
#8 Tests obrigatórios	✅	86 tests + 4 E2E specs

Decisões fixadas pelo orquestrador (master-plan §0)

30 decisões fechando ambiguidades dos 2 .plan.md originais. Principais:

B0 Base = release/v3.8.6 (não v3.8.5)
B2 Migrations 073/074/075 (renumber se Grupo A merge primeiro — trivial via git mv)
B5 Sidebar — activity adicionado, logs-activity mantido em HIDEABLE_SIDEBAR_ITEM_IDS (back-compat de presets), nova seção costs com 4 items + costs-quota-plans adicionado por F9
B16 Enforce hook fail-open em caminho quente (log warn, segue request)
B18 /api/quota/** NÃO LOCAL_ONLY (B19) — usa requireManagementAuth
B24 Coverage gate relaxado de 75/75/75/70 para 40/40/40/40 (autorização do owner, restaurar pós-merge)
B26 Mutations emitem logAuditEvent com actions quota.pool.created|updated|deleted, quota.plan.updated, quota.store.driver_changed
B29 recordConsumption fail-open (drift aceitável; teto global do fetcher corrige)

Documentation

Master plan: _tasks/features-v3.8.6/refactorpages/_orchestration/master-plan-group-B.md (~1500 linhas)
Audit report: _tasks/features-v3.8.6/refactorpages/_orchestration/audit-report-B.md
Plans originais: _tasks/features-v3.8.6/refactorpages/{16,22}-*.plan.md
Docs novos:
- docs/routing/QUOTA_SHARE.md (345 LOC — algoritmo, drivers, pipeline, UI, env vars, troubleshooting)
- docs/architecture/MONITORING_SECTIONS.md (146 LOC)
Docs atualizados:
- docs/architecture/REPOSITORY_MAP.md (+6 entradas)
- docs/reference/openapi.yaml (+491 LOC — 13 paths + 7 schemas)

Migration impact

/dashboard/logs/activity → 308 redirect para /dashboard/activity (permanentRedirect)
Sidebar Costs vem entre Analytics e Monitoring (era subgrupo Costs Parameters em Monitoring)
localStorage pools migram para DB transparentemente na 1ª visita à página (hook useLocalStoragePoolMigration idempotente — não duplica)
Activity feed mostra eventos de HIGH_LEVEL_ACTIONS (allowlist em src/lib/audit/highLevelActions.ts); demais ainda visíveis em Audit Log

Definition of Done — 18/18 itens

13 ✅ verificados em audit headless (lint, typecheck, cycles, unit, vitest, coverage gate, Hard Rules, docs, no Co-Authored-By/--no-verify, branch base correto)
3 ⚠️ SKIP-ENV (E2E reais, Protocol E2E, build prod — requerem display/server)
1 ⏳ owner action (este PR)
1 ⚠️ manual browser test (LS→DB migration — verificar toast + DB state pós-merge)

Post-merge tasks (não bloqueiam este PR)

Restaurar coverage gate para 75/75/75/70 (package.json::test:coverage + CLAUDE.md Hard Rule feat(proxy): enable SOCKS5 proxy support by default #9)
Wire-up QUOTA_SOFT_DEPRIORITIZE_FACTOR em todas as 14 estratégias de combo (F7 aplicou só em auto)
Executar E2E specs: npm run test:e2e -- --grep "group-b"
Teste manual da migração LS→DB: abrir /dashboard/costs/quota-share com dados em localStorage
Build prod: npm run build para verificar chunk lazy do Recharts
Renumerar migrations 073/074/075 → 076/077/078 se Grupo A merge primeiro (per B2)
Coverage catch-up nos críticos para ≥90% local

Test plan

Creates migrations 073 (quota_pools + quota_allocations) and 074 (quota_consumption sliding-window counter). Both are idempotent via CREATE TABLE IF NOT EXISTS and CREATE INDEX IF NOT EXISTS. FK ON DELETE CASCADE from quota_allocations to quota_pools. Fixes B2 IDs.

…B/F2) Implements listPools, getPool, createPool, updatePool, deletePool, upsertAllocations (replace strategy via transaction), and listAllocationsForApiKey. All SQL uses prepared statements. Local type shapes aligned with src/lib/quota/dimensions.ts contract (B13).

Implements getBucket, incrementBucket (atomic UPSERT), getPair (curr+prev for sliding window formula), and gcOlderThan (stale bucket cleanup). Atomic increment uses INSERT ... ON CONFLICT DO UPDATE — no separate read-modify-write cycle needed.

… plans (B/F2) Implements getPlan, listPlans, upsertPlan (idempotent ON CONFLICT DO UPDATE), and deletePlan. Serializes QuotaDimension[] as JSON into dimensions_json column and parses back on read. Malformed JSON returns empty dimensions rather than throwing.

Adds re-export blocks for quotaPools (7 functions), quotaConsumption (4 functions with gcQuotaConsumption alias), and providerPlans (4 functions with getProviderPlan/listProviderPlans/etc. aliases). Zero logic added to localDb.ts — Hard Rule #2 maintained.

Adds QUOTA_STORE_DRIVER, QUOTA_STORE_REDIS_URL, QUOTA_SATURATION_THRESHOLD, QUOTA_SOFT_DEPRIORITIZE_FACTOR, and QUOTA_CONSUMPTION_RETENTION_DAYS as per §3.8 of master-plan-group-B.

… (B/F2) Adds 44 tests across 4 files: - db-quota-pools.test.ts (16 tests): CRUD lifecycle, upsertAllocations replace strategy, FK CASCADE, listAllocationsForApiKey cross-pool. - db-quota-consumption.test.ts (12 tests): getBucket, incrementBucket atomic (100 concurrent), getPair, gcOlderThan boundary semantics. - db-provider-plans.test.ts (10 tests): upsertPlan idempotence, getPlan JSON parsing, listPlans, deletePlan. - db-quota-migrations-idempotency.test.ts (6 tests): schema assertions and double-run idempotency for migrations 073-075.

…gistry)

…ctivity at top (B/F3) - MONITORING_ITEMS reduced to single `activity` item at `/dashboard/activity` - New LOGS_GROUP (logs/logs-proxy/logs-console) extracted from flat monitoring items - New SYSTEM_GROUP (health/runtime) extracted from flat monitoring items - AUDIT_GROUP preserved unchanged - Monitoring section children: [...MONITORING_ITEMS, LOGS_GROUP, AUDIT_GROUP, SYSTEM_GROUP] - COSTS_PARAMS_GROUP removed from monitoring section (items migrate to COSTS_ITEMS) - `activity` added to HIDEABLE_SIDEBAR_ITEM_IDS; `logs-activity` preserved for back-compat (B11) - Updated existing sidebar-visibility.test.ts to match new monitoring item structure

…ystemGroup, costsOverview (B/F3) Add new sidebar i18n keys without removing existing ones (back-compat B11/B12): - sidebar.activity / sidebar.activitySubtitle - sidebar.logsGroup - sidebar.systemGroup - sidebar.costsOverview / sidebar.costsOverviewSubtitle Existing sidebar.costs, sidebar.costsSection, sidebar.costsSubtitle preserved.

Three new test files: - sidebar-monitoring-reorg.test.ts: asserts monitoring has 4 children (activity item + logs/audit/system groups), no costs-parameters group, no logs-activity in items - sidebar-costs-section.test.ts: asserts costs section exists with 4 items in correct order, costs removed from analytics, costs positioned between analytics and monitoring - sidebar-back-compat.test.ts: asserts activity added + logs-activity preserved in HIDEABLE_SIDEBAR_ITEM_IDS, admin preset shows activity and hides logs-activity (B30)

…-key mutex (B/F6)

…vailability) (B/F6)

…n (B/F6)

…, generous/strict modes, cap-absolute) (B/F6)

…B/F6)

…n (B/F6)

… (B/F6)

…) (B/F6)

… saturationSignals + storeFactory (B/F6)

…esolver + burnRate + saturation)

…e duplicate icon span (B/G4) Line 68: {statusCls} string literal → \${statusCls} template literal so status color applies. Remove duplicate <span> wrapping (lines 71-73) that rendered the icon twice via copy-paste bug.

Add stackedBarTitle and usedSuffix keys to quotaShare namespace in both pt-BR and en locales to support the new StackedAllocationBar component.

…s (B/G4) New test file stacked-allocation-bar.test.tsx covers: - empty allocations → null render - 3 segments with correct widths (50%/30%/20%) - 1 segment at 100% - labels without usedSuffix when usage=null - usedSuffix labels when usage provided (consumed/fairShare%) - fallback to apiKeyId when keyLabel missing pool-card.test.tsx updated: mock StackedAllocationBar, assert it renders when pool.allocations is non-empty.

…rowing count (B/G5)

…ive/keys/avg-util/borrowing) (B/G5)

…w (B/G5)

…rePage (B/G5)

…Aggregate (gap #5 closed)

5 gaps (G1-G5) validated and merged into pai. Coverage re-measured: St:79.84% / Br:73.68% / Fn:82% / Ln:79.84% — gate 40/40/40/40 PASS. 57 unit tests + 26 vitest UI tests pass for gap-specific suites.

…al coverage 80%) Gap closure exceeded original 75/75/75/70 requirement. Measured on Group B branch: statements 79.83%, branches 73.68%, functions 82%, lines 79.83% — all above original thresholds. No need to defer restoration to post-merge.

Two gaps found in second-pass code review of Group B: 1. B26 violation: DELETE /api/quota/plans/[connectionId] did not emit logAuditEvent. Per master plan B26, every plan mutation must audit. Now emits quota.plan.updated with metadata.reverted=true to mark the revert-to-auto/catalog semantic. Test integration extended with assertion that audit event is present after DELETE. 2. pt-BR / pt locales had "costsSection": "Costs" (English label) instead of the Portuguese "Custos". Other section labels in the same block are left in English intentionally (analytics, monitoring) — they are project-wide untranslated terms; "Custos" is the established repo translation for the Costs section title. Validation: - npm run typecheck:core: clean - tests/integration/quota-plans-crud.test.ts: 10/10 pass (includes new assertion on DELETE → audit event) - eslint --no-warn-ignored on touched files: clean

…) + fix transform bug Conflicts: migrations 073/074/075->077/078/079 (collision w/ base 073-076); localDb union (quota + tokenLimits/plugins re-exports); i18n en/pt-BR deep-merge (base translations win over __MISSING__ placeholders; sidebar.costsSection=Custos); CLAUDE.md keeps base coverage rule (>=40%). Pre-existing #2859 bugs surfaced by validation & fixed: chatCore onStreamComplete 'await import'->'import().then()' (await was outside async fn, broke tsx transform of 17 chat-* test files); documented 5 QUOTA_* env vars in ENVIRONMENT.md to fix env-doc-sync drift.

…env-doc fixes - bump package.json / open-sse / electron / openapi / llm.txt to 3.8.8 - restructure CHANGELOG: Unreleased -> [3.8.8], dedup broken Notion/MCP block (was 12x) - add every PR since v3.8.7 that was missing: Quota Share Engine (#2859/#3022/#3032), page redesigns (#2827/#2839/#2847/#2849/#2869/#2873), and fixes #2960/#2973/#2984/ #3021/#3029/#3031/#3035/#3036/#3037/#3039/#3043/#3028; folded #2978/#2988/#3041 - insert [3.8.8] section into all 41 i18n CHANGELOGs + sync llm.txt mirrors - document OMNIROUTE_PLUGINS_ALLOW_EXEC in .env.example + ENVIRONMENT.md (env-doc-sync gap)

…) + fix transform bug Conflicts: migrations 073/074/075->077/078/079 (collision w/ base 073-076); localDb union (quota + tokenLimits/plugins re-exports); i18n en/pt-BR deep-merge (base translations win over __MISSING__ placeholders; sidebar.costsSection=Custos); CLAUDE.md keeps base coverage rule (>=40%). Pre-existing cheaper-inference#2859 bugs surfaced by validation & fixed: chatCore onStreamComplete 'await import'->'import().then()' (await was outside async fn, broke tsx transform of 17 chat-* test files); documented 5 QUOTA_* env vars in ENVIRONMENT.md to fix env-doc-sync drift.

…pages-v3-B-monitoring-quota-share feat(monitoring,costs,quota): Monitoring reorg + Costs section + Quota Share Engine (planos 16+22)

…) + fix transform bug Conflicts: migrations 073/074/075->077/078/079 (collision w/ base 073-076); localDb union (quota + tokenLimits/plugins re-exports); i18n en/pt-BR deep-merge (base translations win over __MISSING__ placeholders; sidebar.costsSection=Custos); CLAUDE.md keeps base coverage rule (>=40%). Pre-existing cheaper-inference#2859 bugs surfaced by validation & fixed: chatCore onStreamComplete 'await import'->'import().then()' (await was outside async fn, broke tsx transform of 17 chat-* test files); documented 5 QUOTA_* env vars in ENVIRONMENT.md to fix env-doc-sync drift.

…pages-v3-B-monitoring-quota-share feat(monitoring,costs,quota): Monitoring reorg + Costs section + Quota Share Engine (planos 16+22)

…) + fix transform bug Conflicts: migrations 073/074/075->077/078/079 (collision w/ base 073-076); localDb union (quota + tokenLimits/plugins re-exports); i18n en/pt-BR deep-merge (base translations win over __MISSING__ placeholders; sidebar.costsSection=Custos); CLAUDE.md keeps base coverage rule (>=40%). Pre-existing cheaper-inference#2859 bugs surfaced by validation & fixed: chatCore onStreamComplete 'await import'->'import().then()' (await was outside async fn, broke tsx transform of 17 chat-* test files); documented 5 QUOTA_* env vars in ENVIRONMENT.md to fix env-doc-sync drift.

…pages-v3-B-monitoring-quota-share feat(monitoring,costs,quota): Monitoring reorg + Costs section + Quota Share Engine (planos 16+22)

diegosouzapw added 30 commits May 27, 2026 19:04

feat(quota): add canonical dimensions, types and Zod schemas

70b9cc7

feat(audit): add high-level actions allowlist and activity icons map

93091fb

feat(quota): add provider plan registry with known plans

7a51666

test(quota): cover dimensions, schemas, plan registry

258c676

test(audit): cover high-level actions and activity icons

1b0282e

chore(env): document quota store env vars in .env.example (B/F2)

adb7f2d

Adds QUOTA_STORE_DRIVER, QUOTA_STORE_REDIS_URL, QUOTA_SATURATION_THRESHOLD, QUOTA_SOFT_DEPRIORITIZE_FACTOR, and QUOTA_CONSUMPTION_RETENTION_DAYS as per §3.8 of master-plan-group-B.

merge: F1 shared foundation (types, schemas, audit allowlist, plan re…

282bffc

…gistry)

merge: F2 DB migrations + modules (pools, consumption, plans)

3c50ebc

merge: F3 sidebar Monitoring 3-groups + Costs section + i18n PT-BR/EN

c06d1e1

feat(quota): add QuotaStore facade and types re-export (B/F6)

8a10b3e

feat(quota): add sqliteQuotaStore with sliding window counter and per…

ca85652

…-key mutex (B/F6)

feat(quota): add redisQuotaStore (optional driver, gated by ioredis a…

4bb44b1

…vailability) (B/F6)

feat(quota): add storeFactory with setting/env-driven driver selectio…

6754803

…n (B/F6)

feat(quota): add fairShare work-conserving algorithm (multi-dimension…

9905d92

…, generous/strict modes, cap-absolute) (B/F6)

feat(quota): add burnRate EMA estimator and time-to-exhaustion (B/F6)

c3c0817

feat(quota): add planResolver (DB override > known catalog > empty) (…

23f5b6f

…B/F6)

feat(quota): add saturationSignals reader with 30s cache and fail-ope…

4d825ad

…n (B/F6)

test(quota): cover sqlite store concurrency + sliding window rotation…

c647f85

… (B/F6)

test(quota): cover redisQuotaStore mock (gated by RUN_QUOTA_REDIS_INT…

d5d9b5c

…) (B/F6)

test(quota): cover fairShare 10 scenarios + burnRate + planResolver +…

2212301

… saturationSignals + storeFactory (B/F6)

merge: F6 QuotaStore core (sqlite + redis drivers + fairShare + planR…

b9e5d94

…esolver + burnRate + saturation)

diegosouzapw added 12 commits May 28, 2026 13:51

chore(i18n): pt-BR + en quotaShare.stackedBarTitle + usedSuffix (B/G4)

01d49f5

Add stackedBarTitle and usedSuffix keys to quotaShare namespace in both pt-BR and en locales to support the new StackedAllocationBar component.

merge: G4 StackedAllocationBar + PoolCard bug fix (gap #4 closed)

33c79a8

feat(quota-share): add usePoolsUsageAggregate hook for avg util + bor…

e7014ff

…rowing count (B/G5)

refactor(quota-share): replace stale KPIs with canonical 4 cards (act…

5e79f1e

…ive/keys/avg-util/borrowing) (B/G5)

chore(i18n): pt-BR + en quotaShare.kpiAvgUtilization + kpiBorrowingNo…

a1399ef

…w (B/G5)

test(ui): cover usePoolsUsageAggregate + 4 canonical KPIs in QuotaSha…

944ff0c

…rePage (B/G5)

merge: G5 canonical KPIs (Util média + Em empréstimo) + usePoolsUsage…

bd1ef1a

…Aggregate (gap #5 closed)

docs(orchestration): add Gap closure section to audit-report-B (B/GR)

796145d

5 gaps (G1-G5) validated and merged into pai. Coverage re-measured: St:79.84% / Br:73.68% / Fn:82% / Ln:79.84% — gate 40/40/40/40 PASS. 57 unit tests + 26 vitest UI tests pass for gap-specific suites.

diegosouzapw changed the base branch from release/v3.8.6 to release/v3.8.7 May 29, 2026 22:05

diegosouzapw changed the base branch from release/v3.8.7 to release/v3.8.8 May 30, 2026 04:10

diegosouzapw merged commit 715809a into release/v3.8.8 May 30, 2026
2 checks passed

diegosouzapw deleted the refactor/pages-v3-B-monitoring-quota-share branch May 30, 2026 13:01

diegosouzapw mentioned this pull request Jun 2, 2026

Release/v3.8.8 #2930

Merged

This was referenced Aug 14, 2026

Feature: Team-level Quota Management #687

Closed

feat(teams): billing cost centers, soft budgets and dashboard #10409

Merged

Navigation Menu

Repository navigation

feat(monitoring,costs,quota): Monitoring reorg + Costs section + Quota Share Engine (planos 16+22) - #2859

feat(monitoring,costs,quota): Monitoring reorg + Costs section + Quota Share Engine (planos 16+22)#2859
diegosouzapw merged 98 commits into
release/v3.8.8from
refactor/pages-v3-B-monitoring-quota-share

diegosouzapw commented May 28, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

diegosouzapw commented May 28, 2026

Summary

10 frentes paralelas executadas e mergeadas

Métricas

Hard Rules audit (Group B branch — F10 grep-based)

Decisões fixadas pelo orquestrador (master-plan §0)

Documentation

Migration impact

Definition of Done — 18/18 itens

Post-merge tasks (não bloqueiam este PR)

Test plan

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant