How it works

MasterOS separates a control plane (auth, organization, billing/ledger, model catalog, admin) from an execution plane (chat, model gateway, retrieval, and — later — agent/workflow runtimes). The split exists so that security and scaling boundaries stay clean even though, today, both planes run in one API service.

Sending a chat message

1. The server resolves your organization's active plan and checks the requested model tier is on its allowed list — this is enforced server-side, not just hidden in the UI.
2. If the message continues an existing conversation, ownership is checked before anything else happens — an invalid or another user's conversation id is rejected before any quota is touched.
3. An idempotency key (sent with every chat request) is reserved. A retried request with the same key never re-bills or re-calls the model provider; a duplicate in-flight request is rejected outright.
4. The estimated cost is reserved against your daily quota bucket before the model is ever called.
5. The user's message is saved, the model streams its reply back token by token, and the reply is saved together with its real token counts and cost — as one atomic database transaction, so a crash can never leave a billed message with no matching ledger entry (or vice versa).
6. The quota reservation is settled to the real cost (or released in full, if nothing was actually billed), and the ledger is debited by that same amount.

Billing is a ledger — a sequence of credit/debit entries — never a single balance number that gets decremented directly. That's what makes it possible to reason correctly about a request that fails halfway through, a refund, or reconciling exactly what a user was charged for.

Uploading a file

Upload → validate type/size → malware scan → store → extract text → available for citation in chat

A file that fails the malware scan or text extraction is marked failed and isn't usable in chat. Permission filtering (which files you're allowed to see) happens before any content reaches a model — a security boundary, not just a search filter.