feat: usage table + daily quota accounting

backend/app/config.py

@@ -74,6 +74,12 @@ class Settings(BaseSettings):
     reddit_client_id: str = ""
     reddit_client_secret: str = ""
 
+    # quotas (per UTC day)
+    quota_cards_per_day: int = 10
+    quota_chat_per_day: int = 30
+    quota_connections_refresh_per_day: int = 3
+    quota_ip_cards_per_day: int = 30
+
     # worker / queue
     max_attempts: int = 3
     worker_poll_seconds: float = 1.0

backend/app/quota.py

@@ -0,0 +1,61 @@
+"""Per-user daily quotas. Chat-style routes raise 429; card creation degrades
+instead (see cards.py) so a save never hard-fails."""
+
+from __future__ import annotations
+
+from datetime import datetime, time, timedelta, timezone
+
+from fastapi import Depends, HTTPException, Request
+
+from app.auth import get_owner
+from app.config import get_settings
+from app.store import db
+
+
+def _resets_at() -> str:
+    """ISO timestamp of the next UTC midnight (quota reset)."""
+    now = datetime.now(timezone.utc)
+    tomorrow = datetime.combine(now.date() + timedelta(days=1), time.min, tzinfo=timezone.utc)
+    return tomorrow.isoformat()
+
+
+def spend(kind: str, limit_attr: str):
+    """Dependency factory: spend one unit of `kind` or raise 429."""
+
+    async def _dep(owner_id: str = Depends(get_owner)) -> str:
+        limit = getattr(get_settings(), limit_attr)
+        async with db.session() as s:
+            allowed, used = await db.spend_usage(
+                s, owner_id=owner_id, kind=kind, limit=limit
+            )
+        if not allowed:
+            raise HTTPException(
+                status_code=429,
+                detail={
+                    "error": "quota", "kind": kind,
+                    "used": used, "limit": limit, "resets_at": _resets_at(),
+                },
+            )
+        return owner_id
+
+    return _dep
+
+
+async def card_budget(owner_id: str, request: Request) -> bool:
+    """Card-creation budget. Enforces the per-IP cap (429) and returns whether
+    the owner still has AI budget today (False -> degrade, never fail)."""
+    settings = get_settings()
+    ip = request.client.host if request.client else "unknown"
+    async with db.session() as s:
+        ip_ok, _ = await db.spend_usage(
+            s, owner_id=f"ip:{ip}", kind="cards", limit=settings.quota_ip_cards_per_day
+        )
+        if not ip_ok:
+            raise HTTPException(status_code=429, detail={
+                "error": "quota", "kind": "ip", "limit": settings.quota_ip_cards_per_day,
+                "used": settings.quota_ip_cards_per_day, "resets_at": _resets_at(),
+            })
+        allowed, _ = await db.spend_usage(
+            s, owner_id=owner_id, kind="cards", limit=settings.quota_cards_per_day
+        )
+    return allowed

backend/app/store/db.py

@@ -275,6 +275,8 @@ class JobRow(Base):
     state: Mapped[str] = mapped_column(String, default=JobState.QUEUED.value, index=True)
     attempts: Mapped[int] = mapped_column(Integer, default=0)
     last_error: Mapped[str | None] = mapped_column(Text, nullable=True)
+    # Past-quota card creation: worker skips AI structuring, paragraph fallback.
+    degraded: Mapped[bool] = mapped_column(Boolean, default=False)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
     started_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
     finished_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
@@ -296,6 +298,39 @@ class ConnectionRow(Base):
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
 
 
+class UsageRow(Base):
+    """Daily metered usage. One row per (owner, UTC day, kind); owner_id also
+    stores "ip:<addr>" rows for the anonymous-farming IP cap."""
+
+    __tablename__ = "usage"
+
+    owner_id: Mapped[str] = mapped_column(String, primary_key=True)
+    day: Mapped[str] = mapped_column(String, primary_key=True)  # "YYYY-MM-DD" UTC
+    kind: Mapped[str] = mapped_column(String, primary_key=True)
+    count: Mapped[int] = mapped_column(Integer, default=0)
+
+
+def _today() -> str:
+    """Current UTC day key."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+
+async def spend_usage(
+    db_session: AsyncSession, *, owner_id: str, kind: str, limit: int
+) -> tuple[bool, int]:
+    """Increment today's counter unless at limit. Returns (allowed, used_after)."""
+    day = _today()
+    row = await db_session.get(UsageRow, (owner_id, day, kind))
+    if row is None:
+        row = UsageRow(owner_id=owner_id, day=day, kind=kind, count=0)
+        db_session.add(row)
+    if row.count >= limit:
+        return False, row.count
+    row.count += 1
+    await db_session.commit()
+    return True, row.count
+
+
 # --------------------------------------------------------------------------- #
 # Engine / session lifecycle
 # --------------------------------------------------------------------------- #
@@ -383,6 +418,13 @@ async def init_db() -> None:
                 "owner_id": "TEXT",
             },
         )
+        await _add_missing_columns(
+            conn,
+            "jobs",
+            {
+                "degraded": "BOOLEAN DEFAULT 0",  # quota-degraded card creation
+            },
+        )
         await _add_missing_columns(
             conn,
             "concepts",

backend/tests/test_quota.py

@@ -0,0 +1,21 @@
+"""Quota accounting: daily counters, limits, per-owner/per-kind isolation."""
+
+from app.store import db
+
+
+async def test_spend_usage_counts_and_caps(database) -> None:
+    async with db.session() as s:
+        for i in range(3):
+            allowed, used = await db.spend_usage(s, owner_id="u1", kind="chat", limit=3)
+            assert allowed and used == i + 1
+        allowed, used = await db.spend_usage(s, owner_id="u1", kind="chat", limit=3)
+        assert not allowed and used == 3
+
+
+async def test_usage_is_per_owner_and_per_kind(database) -> None:
+    async with db.session() as s:
+        await db.spend_usage(s, owner_id="u1", kind="chat", limit=3)
+        allowed, used = await db.spend_usage(s, owner_id="u2", kind="chat", limit=3)
+        assert allowed and used == 1
+        allowed, used = await db.spend_usage(s, owner_id="u1", kind="cards", limit=3)
+        assert allowed and used == 1