Workspace isolation
A request is filtered three times before it can see a record: at the edge, where a customer session is served a closed surface; in the object layer, where every read is scoped and every write is stamped automatically; and in the database, which applies its own filter underneath both. The reason for three is blunt — each one can be undone by a single line of code, and it is a different line each time.
The three layers#
| Layer | Where it sits | What it catches |
|---|---|---|
| The customer surface | At the edge, before anything is routed | A customer session asking for anything that is not part of a workspace's surface. Closed by default: what is not permitted is refused rather than attempted |
| The workspace kernel | In the object layer, on every query and every insert | A query that forgot to filter, and a record being created into the wrong workspace. Reads are filtered by an automatic rule rather than by remembering at each call site; writes are stamped with the active workspace |
| Row-level security | Inside PostgreSQL, under everything above | Anything that reaches past the object layer at all. The active workspace is published to the database on every request, so raw access is confined too |
The active workspace itself comes from the authenticated session. It is never read from a request body, a query string or a header — which is why it cannot be steered by anything a browser sends, and why switching workspace is a session action rather than an address you can type.
Why three and not one good one#
The earlier design had one: a list of permitted addresses in a single function. It was correct, and it protected every business's data, and it depended entirely on the operator's surface and the customer's surface being different addresses. Once one engine serves both audiences — which is the whole point of a shared core — that assumption stops holding, and a list of addresses stops carrying the weight it was carrying.
The alternative to structural scoping was editing every query site by hand: well over a hundred of them, where one missed site is a cross-business leak and nothing about the missed site would look wrong in review. Making the default safe and the exception loud is the trade. Reaching across workspaces is possible — the platform has to, to match a payment to whoever is expecting it — but it is explicit, it has to state a reason, and it reads as unusual in a change.
Invisible is not missing#
There is one failure worth naming because it is silent by construction. A record whose workspace stamp is empty matches no scope and no policy. It is therefore omitted from every list — while an action that already knows its identifier still works on it perfectly. The record is invisible, not absent, and nothing raises an error, because from the filter's point of view nothing went wrong.
In practice that meant connected mail identities could disappear from a screen with no duplicate warning and no error, and the check that stops duplicates could not see them either — so reconnecting one would have written a second record for a single real inbox. The listing and the uniqueness check now both ask the one query that can see such rows, and they ask it read-only.
What isolation is not#
- It is not a limit on people. Somebody who is a member of two workspaces can see both; that is membership working, not the boundary failing.
- It is not protection against what a person does with data they may legitimately read. Nothing stops a member forwarding a message.
- It does not extend to a new table on its own. A scoped table has to be listed as scoped and have its database policy applied in the same release; one with a workspace column that nobody listed is scoped by nothing at all.
- It is not a commercial distinction. The operator's workspace is scoped exactly like a customer's; having no plan is a billing fact, not an exemption from the boundary.
Confirming the boundary rather than assuming it is a routine, enumerated check rather than an assertion — see Verifying isolation.
Questions#
Could one workspace's records appear in another's screens?
That would require three independent mechanisms to fail at once, in three different ways. If you ever see records belonging to a business you have no membership in, stop and report it with what you saw and when — it is treated as an incident, not a support question.
Why is the operator not exempt?
Because an exemption is a permanent hole with a friendly name. JBRH's own workspace is one workspace among many and is scoped identically. Reaching across workspaces is a separate, explicit, reasoned action used by the platform's own control plane, not a property of being the operator.
Does a record with a broken workspace stamp put anything at risk?
It is the opposite failure: such a record is visible to nobody rather than to everybody. The harm is silence — a list that omits it without saying so — which is why the listing and the duplicate check were taught to see it and why the repair happens at boot.