# Bucket Usage Audit (2026-02-11)

## What exists
- Buckets table: `buckets` in [packages/db/migrations/005_buckets.sql](packages/db/migrations/005_buckets.sql)
- Entries table: `entries` (pivoted from spendings) in [packages/db/migrations/004_entries_pivot.sql](packages/db/migrations/004_entries_pivot.sql) and base definition in [packages/db/migrations/001_init.sql](packages/db/migrations/001_init.sql)
- Tags storage: `tags`, `entry_tags`, `bucket_tags` in [packages/db/migrations/002_tags.sql](packages/db/migrations/002_tags.sql) and [packages/db/migrations/005_buckets.sql](packages/db/migrations/005_buckets.sql)
- Recurrence fields: `entries.is_recurring` plus recurrence columns in [packages/db/migrations/004_entries_pivot.sql](packages/db/migrations/004_entries_pivot.sql)
- Necessity enum (entries): `spending_necessity` in [packages/db/migrations/001_init.sql](packages/db/migrations/001_init.sql)
- Existing usage calc: `totalSpent` based on tag overlap in [apps/web/lib/server/buckets.ts](apps/web/lib/server/buckets.ts)
- Bucket API routes: [apps/web/app/api/buckets/route.ts](apps/web/app/api/buckets/route.ts) and [apps/web/app/api/buckets/[id]/route.ts](apps/web/app/api/buckets/[id]/route.ts)

## Missing before this change
- Bucket `necessity` (no column or API fields)
- Bucket `windowDays` (no column or API fields)
- Bucket usage rules for recurrence/necessity/date window
- Entry necessity value `BOTH` (enum was aligned to `BOTH`)

## Endpoints impacted
- Buckets list/create/update in [apps/web/app/api/buckets/route.ts](apps/web/app/api/buckets/route.ts)
- Buckets update/delete in [apps/web/app/api/buckets/[id]/route.ts](apps/web/app/api/buckets/[id]/route.ts)
- Entries and recurring entries endpoints for necessity validation

## Notes
- Tag matching uses `bucket_tags` and `entry_tags` join tables.
- Recurrence flag is `entries.is_recurring`.
- `occurred_at` is `date` in the DB (not timestamp).
- `windowDays` default set to 30 (min 1, max 365).
- Necessity uses `spending_necessity` enum with `BOTH`.