Data schema catalog

One Postgres database, partitioned into schemas by domain. This is a map of the important tables — for relationships and the money primitives see the data model overview and token ledger & money path.

`identity`

Table	Purpose
`users`	Canonical user (id, email, username)
`user_auth_identities`	Provider ↔ user mapping (`(provider, subject)`) for JIT provisioning
`workspaces`	A user’s workspaces
`workspace_members`	Membership + roles

`billing`

Table	Purpose
`token_balances`	Per-user balance (`base_tokens`, `extra_tokens`, `base_expires_at`)
`token_ledger`	Append-only audit of every deduct/refund/grant, with an idempotency key
`subscriptions`	Active subscription + period
`plan_prices`	Plan/price catalog (incl. IAP product-id columns)
`email_grants`	Comp/trial grants by email or domain

`generation`

Table	Purpose
`tasks`	The Postgres-as-queue table (status, lease, retries, reservation, settlement)
`tools`	Registered tools (input/output JSON schema)
`tool_configs`	Per-tool config (pricing scope)
`tool_config_licenses`	Per-license pricing rows
`credentials`	Tool provider credentials (`secret_ref`)
`rate_limits`	Per-tool rate-limit rows

`storage`

Table	Purpose
`blobs`	Content-addressed blob (`hash` PK, `blob_url`, size, mime)
`files`	A user-visible file referencing a blob (ownership, visibility)
`file_lyrics`	Timed/plain lyrics side table
`file_provenance`	Provenance/lineage graph
`attributes`	Scoped durable per-file metadata (`scope`, `value_json`, `owner`)
`file_license`	Per-file license record

`chat`

Table	Purpose
`projects`	A chat/generation project
`messages`	Conversation turns; a message can trigger a task

Data model overview — the ER diagram + tiers
The token ledger & money path — billing tables in motion
Add durable per-file metadata — the attributes side table
Proto contract reference — how these tables are reached