Modelling practices¶
One rule covers most questions teams bring: structure in the model, policy in the data.
The model is the vocabulary: which object types exist, which relations they have, how a relation derives from another. An app sets it in its fragment at registration, and changes it by registering again, which is superadmin work, like changing a schema. Policy is who holds what, and every piece of it is a tuple your app grants and revokes at runtime through the grants route, with no administrator involved. When a question sounds like "can the model change at runtime", the answer is almost always "that is not a model change".
A role matrix is tuples¶
A Director edits "which deal role may do what" on a page, live. That is not a model change.
Model, fixed at registration:
"deal": {
"company_module": { "this": true },
"role": { "this": true },
"viewer": { "union": [ { "this": true }, { "tupleToUserset": { "tupleset": "role", "computedUserset": "member" } } ] },
"editor": { "union": [ { "this": true }, { "tupleToUserset": { "tupleset": "role", "computedUserset": "member" } } ] },
"approver": { "union": [ { "this": true }, { "tupleToUserset": { "tupleset": "role", "computedUserset": "member" } } ] }
},
"deal_role": {
"company_module": { "this": true },
"member": { "this": true }
}
Each row of the matrix is one tuple. "Delivery Lead may approve deal D":
deal:D # approver @ deal_role:delivery-lead-D#member
A tick on the page grants it, an untick revokes it, and every Delivery Lead gains or loses
approver on their next check. Membership is the same shape:
deal_role:delivery-lead-D # member @ user:<bob's subject>
One role object per deal keeps the rows company-bound through the anchors. For a matrix that
applies to every deal of a kind, put the rows on one object the deals inherit from through a
parent tuple, as in folders.
The only thing the Director cannot do on that page is invent a new verb, say "export". That is a new relation, so it is a re-registration, and that is right: a new verb has to be enforced in your code before it means anything.
"And" is an intersection¶
"Delivery sees a line only if the line is on the delivery side and they are on the deal" is two facts joined by "and", and the model says it directly:
"line": {
"company_module": { "this": true },
"deal": { "this": true },
"delivery_side": { "this": true },
"on_deal": { "tupleToUserset": { "tupleset": "deal", "computedUserset": "member" } },
"viewer": { "intersection": [ { "computedUserset": "delivery_side" }, { "computedUserset": "on_deal" } ] }
}
A check holds only when every child holds. Before 0.2.0 the model had no intersection, and the pattern below still works on any version: your app knows both facts, so it writes one tuple that already means both:
deal:D # delivery_viewer @ user:<alice> when Alice joins deal D on the delivery side
line:L # deal @ deal:D on a delivery-side line
line:L # sales_deal @ deal:D on a sales-side line
with line.viewer deriving through deal → delivery_viewer and sales_deal → sales_viewer.
Every check is one walk. The cost is yours: revoke the derived tuple when either fact stops,
and let the reconciliation sweep from Module inside or app beside
catch what a crash missed.
Inheritance, breaking it, limited access¶
Inheritance is a parent tuple, breaking it deletes that tuple and copies the grants to keep,
limited access is a direct grant on the object. No exclusion is needed and none exists.
Modelling folders works it through with tuples and checks.
What is a grant, what is a re-registration¶
| Change | What it is |
|---|---|
| Give someone, a position or a group access to an object | A grant |
| Take it away | A revoke |
| A role may now do one more thing on an object | A grant of the relation to the role's member |
| A new object joins a folder, a deal, a project | A grant of its parent or deal tuple |
| An object moves | Grant the new parent tuple, then revoke the old |
| A new kind of thing to protect (a new object type) | A re-registration |
| A new verb (a new relation), or a new way a relation derives | A re-registration |
| A relation should also be implied by another | A re-registration |
A re-registration replaces the fragment in place and leaves every tuple as it is. Removing a relation that tuples still name makes those tuples inert, not invalid; revoke them first if the ledger should say so.