> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/documentation/core-concepts/tenants-accounts-and-operations.md).

# Tenants, accounts & operations

Authoritative tenant, account, operation, reservation, callback and atomic-value concepts.

SONIC separates durable business identity from provider, wallet and client state. **Client state is never authoritative for money, rewards, permissions, balances, entitlements or settlement.**

## Core concepts

| Concept                  | Definition                                                                                                                                          |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tenant**               | Ownership boundary for accounts, idempotency, credits, subscriptions, operations, policies and audit state.                                         |
| **User ID / Account**    | `userId` comes from the signed session. A tenant-scoped Account carries the server-authoritative role and permissions.                              |
| **Operation**            | Durable logical request that survives retries, provider job replacement, polling fallback and provider callbacks.                                   |
| **Reservation**          | Temporary hold of atomic AI/SaaS credits before external work is dispatched.                                                                        |
| **Settlement / release** | Success settles a credit reservation; a pre-settlement technical failure releases the hold. A release is **not** a customer payment refund.         |
| **Price snapshot**       | Immutable price, currency, decimals, fee, license and policy fields stored on historical commerce state.                                            |
| **Callback stage**       | Provider lifecycle event merged monotonically rather than blindly overwriting later state.                                                          |
| **Atomic amount**        | Integer interpreted only with explicit decimals and currency/token identity.                                                                        |
| **Wallet identity**      | Verified record proving control of one public wallet address inside the authenticated session.                                                      |
| **Transaction intent**   | Scoped business authorization containing wallet, recipient, mint, positive atomic amount, decimals, expiry and settlement threshold before signing. |
| **Signature**            | Evidence that the wallet approved a prepared transaction; not proof that settlement completed.                                                      |
| **Reconciliation**       | Trusted observation of processed, confirmed or finalized chain/provider state that completes a business transition.                                 |

## Generation lifecycle

```
REQUEST → VALIDATE → RESERVE CREDITS → PROVIDER JOB
        → PROCESSING → CALLBACK / POLL FALLBACK
        → NORMALIZE RESULT → SETTLE CREDITS → SAVE ASSETS
```

Provider failure releases a held credit reservation. This reverses a temporary internal hold; it is not a commercial Marketplace refund.

## Callback guarantee

Callback receipt creation, operation mutation, credit settlement/release and the versioned outbox event commit together. Duplicate callback identities replay safely. Stale stages cannot regress a later stage and the **first terminal callback wins**.

Read endpoints may poll the provider as a fallback when callbacks are delayed or unavailable; the internal `GenerationOperation.id` remains authoritative throughout.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/documentation/core-concepts/tenants-accounts-and-operations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.