Markings & Governed Retrieval

Instance-level security for the Org Knowledgebase — gate individual rows to who is cleared, keyed to your org chart, enforced on every read.

Partitions decide which knowledgebase a row lives in. Markings decide who, inside the org, may read an individual row — independent of the partition. This is how "SLT can read SLT documents, but a normal employee cannot" is enforced at the level of a single row, not a whole partition.

A marking is satisfied by your org chart — functional roles (CEO, CTO, Engineer…) and seniority — not by access-control roles. An org owner who is not assigned the relevant functional role can configure a marking but can never read content behind it. There is no admin bypass.

What a marking is

A marking is a named, org-scoped security label (e.g. slt, finance, pii). Each marking defines the predicate that satisfies it:

satisfyingFunctionalRoles — holding any of these org-chart functional roles satisfies the marking.
minSeniorityLevel — a seniority floor; being at or above it satisfies the marking.
departments — department membership (see the note at the end — currently gated).

A caller may read a row if and only if they satisfy every marking on it (deny-by-default, AND across markings). Unknown or unresolved markings fail closed — the row is never returned.

Defining a marking

Create the marking

POST /org-kb/markings
{
  "slug": "slt",
  "displayName": "Senior Leadership Team",
  "satisfyingFunctionalRoles": ["ceo", "cto", "cfo"],
  "minSeniorityLevel": "executive",
  "humanReviewAllowed": false
}

Config authority

You may only create (or change) a marking you yourself satisfy. A non-SLT administrator cannot mint or weaken an slt marking — so sensitive access can never leak through the configuration plane. List existing markings with GET /org-kb/markings.

Apply it

Markings ride onto a row at promotion time as the union of the source's markings and the target partition's baseline markings — promotion can only raise sensitivity, never lower it.

Governed retrieval

Every read path enforces markings the same way, and always pre-filters (denied rows never appear in results, counts, or rankings — they are absent, not redacted):

Org KB query — POST /org-kb/query resolves your org-chart identity and drops every row whose markings you don't satisfy before any results are returned.
Field redaction still applies on top: confidential / restricted properties are redacted from rows you can see.

If your identity can't be resolved, retrieval fails closed — you see only unmarked rows.

Zero-exposure promotion

A marking with humanReviewAllowed: false means its content must never be seen by a human reviewer. Promotions carrying such a marking take the auto-approve path (system actor) or are rejected — no person is ever assigned as a reviewer, and a reviewer is only ever eligible if they themselves satisfy the request's markings. This lets sensitive material flow into the org corpus without an uncleared administrator ever reading it.

Departments are not yet a marking dimension. user.department is free-text today; gating access on it is unsafe. Department-scoped markings (Finance-only, Legal-only) activate once departments become a structured, assignable entity. Until then, model leadership/clearance access with functional roles and seniority.