eryao/docs/protocols/common/user-points-chat-data-protocol.md

# User Points & Chat Data Protocol

This protocol defines the canonical data contract for user profile, points account, points ledger, chat session, and chat messages.

Protocol verification status:

- Last audited migration: `backend/alembic/versions/20260413_0004_register_bonus_claims_snapshot.py`
- Last audited models: `backend/src/models/profile.py`, `backend/src/models/user_points.py`, `backend/src/models/points_ledger.py`, `backend/src/models/points_audit_ledger.py`, `backend/src/models/register_bonus_claims.py`, `backend/src/models/agent_chat_session.py`, `backend/src/models/agent_chat_message.py`
- Current status: aligned with register bonus moved to application service

## Scope

- `profiles`
- `user_points`
- `points_ledger`
- `points_audit_ledger`
- `register_bonus_claims`
- `sessions`
- `messages`

## Compatibility strategy

- Current strategy: additive evolution.
- Breaking changes (drop/rename/type change on core fields) require explicit migration + rollback notes.
- `points_ledger.metadata.schema_version` is mandatory and current value is `1`.

## Runtime charging policy (chat)

- Charge unit: `20` points per successful run.
- Charge timing: deduct after worker run succeeds (`RUN_FINISHED` path).
- Failure behavior: failed/canceled runs do not deduct points.
- Precheck: before accepting a run, backend must verify `available = balance - frozen_balance >= 20`.
- Session follow-up cap: one session allows at most 2 user runs total (initial divination + 1 follow-up).
- Billing idempotency key for per-run consume: `chat.run.success:{sha1(session_id:run_id)}`.
- Failed/canceled runs do not deduct user points. If real provider cost is observed, audit record is written with `billed_to='platform'`.

## Table contract

### profiles

- PK: `id` (`auth.users.id`, `on delete cascade`)
- Core fields: `username`, `avatar_url`, `bio`, `settings`, `referred_by`, `created_at`, `updated_at`, `deleted_at`
- Constraints:
  - `username` not empty
- Indexes:
  - `ix_profiles_username`
  - `ix_profiles_settings_gin`
- Notes:
  - `referred_by` is FK to `profiles.id` (`on delete set null`) for invite/referral tracking
  - `settings` stores `ProfileSettingsV1` JSON including `preferences`, `privacy`, `notification`, `divination_tutorial`

### user_points

- PK: `user_id` (`auth.users.id`, `on delete cascade`)
- Core fields: `balance`, `frozen_balance`, `lifetime_earned`, `lifetime_spent`, `version`, `created_at`, `updated_at`
- Constraints:
  - all numeric totals must be non-negative
  - `frozen_balance <= balance`

### points_ledger

- PK: `id`
- FK:
  - `user_id -> auth.users.id` (`on delete cascade`)
  - `biz_id -> sessions.id` (`on delete restrict`, nullable)
  - `operator_id -> auth.users.id` (`on delete set null`)
- Core fields: `direction`, `amount`, `balance_after`, `change_type`, `biz_type`, `biz_id`, `event_id`, `operator_id`, `metadata`, `created_at`, `updated_at`
- Constraints:
  - `amount > 0`
  - `direction in (1, -1)`
  - `balance_after >= 0`
  - `change_type in ('register', 'consume', 'grant', 'adjust')`
  - `biz_type is null or biz_type='chat'`
  - biz binding:
    - `register => biz_type is null and biz_id is null`
    - `consume/grant/adjust => biz_type='chat' and biz_id not null`
  - direction and change_type coupling:
    - `register/grant => direction = 1`
    - `consume => direction = -1`
    - `adjust => direction in (1, -1)`
  - idempotency: `unique (user_id, event_id)`

### points_audit_ledger

- PK: `id`
- No FK to `auth.users` for `user_id_snapshot` to avoid cascade delete and preserve audit retention
- Core fields: `event_id`, `user_id_snapshot`, `user_email_snapshot`, `change_type`, `biz_type`, `biz_id`, `direction`, `amount`, `balance_after`, `billed_to`, `run_id`, `request_id`, `input_tokens`, `output_tokens`, `cost`, `metadata`, `created_at`, `updated_at`
- Constraints:
  - `amount >= 0`
  - `direction in (1, 0, -1)`
  - `balance_after >= 0`
  - `change_type in ('register', 'consume', 'grant', 'adjust')`
  - `biz_type is null or biz_type='chat'`
  - `billed_to in ('user', 'platform')`
  - metadata must be object
  - idempotency: `unique (event_id)`

### register_bonus_claims

- PK: `id`
- Core fields: `email_hash`, `user_email_snapshot`, `first_user_id_snapshot`, `balance_snapshot`, `grant_event_id`, `has_purchased_starter_pack`, `created_at`, `updated_at`
- Constraints:
  - `email_hash` unique
  - `grant_event_id` unique
- Notes:
  - `email_hash` must be HMAC-SHA256 over normalized email (`trim + lower`)
  - key source: backend config `points_policy.register_bonus_hmac_key`
  - `balance_snapshot` stores the latest pre-delete account balance for same-email re-registration recovery
  - `has_purchased_starter_pack` tracks whether user has purchased the starter pack ($0.99/60 credits)

#### points_ledger.metadata (schema_version=1)

Canonical shape:

```json
{
  "schema_version": 1,
  "operator_type": "user|system|admin",
  "run_id": "string",
  "request_id": "string|null",
  "charge": {
    "message_id": "uuid",
    "message_seq": 1,
    "model_code": "string",
    "input_tokens": 0,
    "output_tokens": 0,
    "cost": "0.000000"
  },
  "ext": {}
}
```

JSON constraints:

- Common:
  - must be object
  - `schema_version = 1`
  - `operator_type in (user, system, admin)`
  - `run_id` non-empty
  - if present, `ext` must be object
- Per `change_type`:
  - `register`: no `charge`, and no chat binding (`biz_type/biz_id` both null)
  - `consume`: requires `charge` object with required fields
  - `grant`: no extra metadata shape requirement
  - `adjust`: requires `ext.ticket_id` non-empty

## Signup initialization contract

- DB trigger (`auth.users` after insert):
  - Function: `public.initialize_profile_and_invite_code_on_signup()`
  - Side effects: profile init + invite code init
- Application service (in `POST /auth/email-session`):
  - `grant_register_bonus_if_eligible()` restores `balance_snapshot` first when present; otherwise grants register bonus via `register_bonus_claims`
  - Bonus amount from `config.points_policy.register_bonus_points`

### sessions

- PK: `id`
- FK: `user_id -> auth.users.id`
- Core fields: `session_type`, `job_id`, `title`, `status`, `last_activity_at`, `message_count`, `total_tokens`, `total_cost`, `state_snapshot`, `created_at`, `updated_at`, `deleted_at`
- Constraints:
  - `session_type in ('chat', 'automation')`
  - `status in ('pending', 'running', 'completed', 'failed')`
  - `message_count/total_tokens/total_cost` non-negative

### messages

- PK: `id`
- FK: `session_id -> sessions.id` (`on delete cascade`)
- Core fields: `seq`, `role`, `content`, `model_code`, `tool_name`, `input_tokens`, `output_tokens`, `cost`, `latency_ms`, `visibility_mask`, `metadata`, `created_at`, `updated_at`, `deleted_at`
- Constraints:
  - `unique (session_id, seq)`
  - `seq > 0`
  - `role in ('user', 'assistant', 'system', 'tool')`
  - token/cost non-negative
  - `latency_ms` null or non-negative

## Security and ownership

- Backend service must derive owner identity from verified auth context.
- Client must not be trusted for `user_id`/`operator_id` ownership semantics.
- `metadata` and `settings` must not include secrets.

## Application initialization contract

Application initialization is split into two separate concerns: deterministic seed data and dynamic notification template sync. These are intentionally decoupled to avoid non-deterministic side effects during bootstrap.

### Seed data (deterministic)

Managed by `python -m core.runtime.cli init-data` (called by `dev-migrate.sh bootstrap`):

- `initialize_llm_catalog()` — seeds `llm_factory` and `llms` tables with known model definitions
- `initialize_system_agents()` — seeds `system_agents` table

These are idempotent and version-locked to code; they do not depend on runtime state or user data.

### Notification templates (declarative sync)

Managed by `python -m core.runtime.cli sync-notifications [flags]`:

- Reads notification definitions from YAML files under `backend/src/core/config/static/notification/notifications/`
- Syncs to `notifications` table; links existing users via `user_notifications` when `--reconcile-targets` is set
- Supports flags:
  - `--dry-run` — validate without writing
  - `--prune` — remove static notifications no longer present in YAML files
  - `--reconcile-targets` — insert `user_notifications` entries for all existing users matching each notification's `target` predicate
  - `--source-key <key>` — sync only the notification with the matching `source_key`

Run after migrations on fresh environments or after adding new notification YAML definitions. Not included in `bootstrap` to keep bootstrap fast and free of unintended side effects.

## Packages API

### GET /api/v1/points/packages

Returns available purchase packages for the current user's region, including starter pack eligibility.

**Request:**
- Auth: Required (JWT)
- Headers: `Authorization: Bearer <token>`

**Response:**
```json
{
  "region": "US",
  "currency": "USD",
  "packages": [
    {
      "productCode": "new_user_pack_099_60",
      "type": "starter",
      "priceUsd": "0.99",
      "credits": 60,
      "badge": null,
      "isStarter": true,
      "starterEligible": true,
      "sortOrder": 0
    },
    {
      "productCode": "basic_pack_499_100",
      "type": "regular",
      "priceUsd": "4.99",
      "credits": 100,
      "badge": null,
      "isStarter": false,
      "starterEligible": false,
      "sortOrder": 10
    }
  ]
}
```

**Fields:**
- `region`: ISO 3166-1 alpha-2 country code (e.g., "US", "CN")
- `currency`: ISO 4217 currency code (e.g., "USD")
- `packages`: List of available packages
  - `productCode`: Unique product identifier
  - `type`: "starter" (new user pack) or "regular"
  - `priceUsd`: Price in USD (decimal string)
  - `credits`: Number of credits
  - `badge`: Optional badge text (e.g., "Popular")
  - `isStarter`: Whether this is a starter pack
  - `starterEligible`: Whether user is eligible to purchase starter pack
  - `sortOrder`: Display order (ascending)

**Business Logic:**
1. Determine user's region from `profile.settings.preferences.country` (default: "US")
2. Load package configuration from `backend/src/core/config/static/packages/{country}.yaml` (fallback to `default.yaml`)
3. Check starter pack eligibility:
   - If `register_bonus_claims.has_purchased_starter_pack = true`, exclude starter pack from response
   - Otherwise, include starter pack with `starterEligible: true`

**Configuration Files:**
- Path: `backend/src/core/config/static/packages/`
- Format: YAML
- Example: `us.yaml`

```yaml
region: US
currency: USD
packages:
  - product_code: new_user_pack_099_60
    type: starter
    price_usd: "0.99"
    credits: 60
    badge: null
    sort_order: 0
    enabled: true
  - product_code: basic_pack_499_100
    type: regular
    price_usd: "4.99"
    credits: 100
    badge: null
    sort_order: 10
    enabled: true
```

**Country/Region Codes:**
- Uses ISO 3166-1 alpha-2 standard
- Default: `US` (United States)
- Examples: `CN` (China), `TW` (Taiwan), `HK` (Hong Kong), `JP` (Japan)