Skip to content

Browser mutations and owning transactions

A browser mutation submits an explicit operation to its owning boundary. Ordinary company edits commonly use Supabase under RLS. Privileged portals, contextual operations, integrations and revisioned transactions use an API and, where needed, one database RPC. The hook coordinates input, request and query refresh; it does not replace server or SQL authorization.

The operation determines the path. Adding a form to an office page does not make a privileged transaction ordinary CRUD. Application data paths explains that choice across layers.

Browser operation Owning path Required result interpretation
Ordinary supported quote field update Supabase mutation under RLS Accepted row update; no implied send or acceptance
Quote creation create_quote_with_thread RPC, or contextual API when linked to an opportunity Native draft identity and its creation contract
Revisioned quote draft persistence API PUT /api/quotes/{id}/draft and save_quote_draft_api Accepted snapshot and new revision; 409 retains local work
Purchase-cost allocation API and save_purchase_cost_allocations Matching revision/source basis and reviewed allocation result
Customer grant invitation/revocation Scoped customer-portal API Explicit grant operation and delivery outcome where applicable
Provider action Domain API/service Operation-specific intent, receipt and uncertainty contract

Hooks obtain session/company context from the verified auth provider. The backend still derives its own accepted-token context and validates target ownership. Supplied IDs, company fields and generated TypeScript types are not authority.

The quote editor prepares a snapshot and fingerprint. It sends expected_updated_at and accepts the returned timestamp only after the owning operation succeeds. The shared draft coordinator controls timing and concurrency; the API/RPC controls allowed fields, revision and domain invariants.

Purchase-cost saving additionally sends expected_revision, basis_fingerprint, reviewed rows and duplicate acknowledgement. The API requires principal staff with invoice read/update, verifies the invoice in that tenant and resolves an active actor before the RPC. It does not turn an allocation into a supplier-payment or AP-approval mutation.

TanStack Query mutations have automatic retry disabled by default. onSuccess invalidates named tenant-key families. This makes dependent lists and totals eligible for refetch; it is not the transaction commit itself. Some callbacks await refreshes so navigation or review can observe the next state.

An editor must retain unsaved work after a rejection and avoid announcing a newer local snapshot as persisted merely because an earlier request returned. usePersistedDraft queues edits made in flight and protects its own draft generation. Company switches and page changes also need the leave-guard contract.

Not every editor uses background persistence. Project, invoice and cost review flows own their explicit saves and decisions. Extracting shared hooks must preserve those boundaries instead of imposing one generic retry model.

A stale version means the reviewed state changed. The caller reads current data and either merges supported changes or obtains a new decision. It must not automatically advance the expected revision and replay stale intent.

The quote helper bounds supported PUT requests to 20 seconds and tells the user to reload to determine whether saving completed. An abort does not roll back a transaction. For provider actions, a lost response can also leave remote state uncertain; API error diagnosis and integration recovery determine the next step.

A synthetic office user assigns a supplier invoice to two projects. The first request uses the reviewed revision/fingerprint. If another edit wins, the UI retains those proposed shares and the API returns a conflict without accepting the stale allocation. After a successful reviewed save, invalidation refreshes project economics; it does not itself create accounting entries.

The named hooks, route handlers and tests establish representative request shapes and state transitions. They do not establish every mutation’s transactionality, all cross-company races or real provider acceptance. Those claims need the owning operation’s tests and receipts.