Never-rules

Rows that nobody may see, no matter what — sensitive locations, legal holds, and the one rule that beats every role, share and flock.

#Never-rules

One day a volunteer on Emu Watch logs a sighting at a nesting site. The birds are breeding, the location is fragile, and a point on a public map would bring people to it. The requirement is not "hidden from the public". Not "visible only to rangers". Gone, for everyone: not the Coastal Volunteers it was shared with, not the Rangers, not even Sam — until the season ends.

Flocks are crews in the API, and your Nest — the site you sign in to — is a project there.

Everything else in the permission system adds. A role allows actions, a share adds reach, a flock is an audience, a collection rule opens records to everyone. None of them can express subtraction — and a system built only out of additions has a frightening property: one over-generous rule anywhere, ever, and the nesting site is on the map again.

A never-rule is the one piece that subtracts:

Records where "sensitive" is true may not be seen by anyone, no matter what.

Sam writes that rule once. From then on, marking any sighting's sensitive field true removes it from every list, every search, every share, every flock, and the public map — for everybody.

#What a never-rule is

A never-rule names a collection (or every collection), a condition, and a reason. Rows matching the condition stop existing, as far as anyone asking is concerned:

  • Reads do not return them. Lists and searches skip them; fetching one by id is "not found".
  • Writes cannot touch them. A row you cannot see is a row you cannot edit, delete, or share — it is "not found" there too, and for the same reason: the same condition decides both.

Three properties are deliberate, and they are what make it safe to rely on:

Rows only. A never-rule removes records. It never changes what an action means and never hides individual columns — a rule that could do those things would be a second permission system to audit, not a fence around the first one.

It is terminal. The rule applies after everything else: after every role, after every share, after every flock and collection rule, after every administrator bypass. There is no combination of permissions that outranks it. That is the point — it exists so that one mistake somewhere else cannot expose what must stay hidden.

Adding one is always safe. Never-rules only ever remove rows, so a new rule cannot accidentally widen anything. Where several rules cover the same collection, all of them apply.

#When to reach for one

Reach for a never-rule when the requirement contains the words "no matter what":

  • A sensitive location. Emu Watch's case: sightings whose coordinates must not reach anyone while the birds are nesting, without deleting them — the record and its history stay intact for the survey, and removing the rule (or clearing the field) brings the sighting back exactly as it was.
  • A legal hold. Records where legal_hold is true may not be seen by anyone — set once, and no future role, share, or collection rule needs to remember it.

And do not reach for one when a plainer piece fits. "Volunteers should not see each other's drafts" is what a role sees on its own; "only rangers may verify" is a role's field rules; "the public sees only verified sightings" is a collection rule. A never-rule is for the small set of things that must stay hidden even if every one of those is misconfigured.

#Why a reason is required

Every never-rule carries a written reason, and the API refuses one without it.

This is not paperwork. A never-rule is invisible by design — rows are simply not there, with no error and no trace in the result. The first person to hit one unexpectedly is looking at a sighting that has stopped existing, and the reason is the difference between "ah — the nesting-site rule" and an afternoon lost to debugging the permission system. The reason is shown wherever the rule's effect is reported.

#Why never-rules bind admins by default

A fence that administrators can step over is a suggestion. Sensitive locations and legal holds are usually about what operators of the site may see, not just members — so by default a never-rule binds everyone, super-admins included.

The escape hatch is explicit, per rule: create one with bindsSuperAdmin: false and super-admins are exempt from that rule only. Use it when the requirement is "hidden from the site, but the operator must still be able to inspect it". The default stays binding because the operator who needs the exemption knows they need it, and the one who forgets should be locked out with everyone else — that is the failure the feature exists for.

One reassurance: a never-rule hides rows, not itself. Whoever manages never-rules can always list them and delete them — deleting the rule is how the rows come back. A rule that hid the way to undo it would be a trap, not a fence.

#The API

Never-rules are called restrictions in the API. Managing them requires the system/roles manage permission — the people who can hand out access are the people who can fence it.

List a Nest's rules:

GET /api/v1/restrictions

Create one:

POST /api/v1/restrictions
{
  "resource": "collections/sightings",
  "filter": { "sensitive": { "_eq": true } },
  "reason": "Nesting sites withheld under the survey protocol",
  "bindsSuperAdmin": true
}
  • resource — collections/<name>, or * for every collection in the Nest.
  • filter — which rows to remove, in the same condition vocabulary as a permission's row rule. It must not be empty, and it is compiled when you create it: a filter that does not compile is refused now, not discovered later.
  • reason — required, as above.
  • bindsSuperAdmin — optional; defaults to true.

Delete one:

DELETE /api/v1/restrictions/:id

There is deliberately no update. Changing a rule is delete + create, so the audit trail shows the old rule ending and the new one starting — never one rule quietly coming to mean something else under the same id.

A new rule takes effect everywhere within a few seconds; creation and deletion are both recorded in the audit log.

#Next

  • Who can see what — where never-rules sit among the seven pieces
  • Recipes — the nesting-site rule, worked end to end
  • Roles — the additive half of the model