14. Access

This chapter says who holds data, who may do what to which record, and how people and systems relate to records without being given anything. Proving who a caller is belongs to the host (chapter 7.6); everything here is decided inside CRUBAL, from data, and logged.

Two things are kept apart. Ownership is holding the key to data: it belongs to owners alone (14.1). Administration is who may manage what inside an owner's data: it is carried by edges (14.3), and the same mechanics apply at every depth. One structure carries all of administration and every relationship: the edge. Delegated control, taking part, viewing, following and paid subscriptions are all edges, so the same checks, history and revocation apply to every one of them.

14.1 Owners and the key #

• A caller is a record: a person, an organization or a system. Edges name callers by ID.

• An owner holds the key. An owner is a domain (a tenant of a platform, or a site of its own; Media Encyclopedia is one), or a person hosted by one. Every record names its owner in its envelope (chapter 1.1).

• Only the owner may: erase (redaction, chapter 8.5.2), export everything it owns, grant edges to callers of other owners (14.8), transfer ownership, and close its data. No edge carries these.

• People own aspects of their own data. A package declares which records a person may own, by kind or class:

  ownership:
    person: Collection, List, Note, Profile
  

  A person's owned records live in the host's store but in their own log chain (chapter 8.5), so they can be exported or moved whole, and erased by them alone. The host signs that chain on their behalf until they publish a key of their own, which the host lists under its well-known keys by the person's ID (chapter 11.7). When the host installs a package version, it restamps their records too, in their chain, with by: migration (chapter 10.4). The host owns everything else, including the facts a person contributes to shared records: those are values with sources (chapter 1.9), not owned records.

• The platform above owners has no default access. A service that hosts many owners reaches an owner's records only through an edge that owner grants (14.8), or, for a legal order or a security incident only, an emergency edge under published terms (14.13). Every use of either is logged.

14.2 Containment: within #

within is an envelope link (chapter 1.1) from a record to the record it belongs to for access: a session within a facility, a league within a session, a team within a league. It nests to any depth and across kinds.

• A record is within at most one record. The links MUST NOT form a cycle.
• within is not of. of is a level of one kind, where values fold (chapter 1.7). within carries access and never moves a value. A lower record is of the record above without being within it (a seller's unit is of a shared product): whoever administers the shared record doesn't administer every record below it.
• Ancestors. A record's ancestors are every record up its within chain. A store MUST keep each record's ancestors so that an access check is a lookup, never a walk, at any depth. Changing a within link is an envelope write (chapter 8.5), and the store updates the ancestors of everything below it.
• Membership is not containment. A person who plays on a team is not within the team. They hold an edge to it (14.3). Their own record stays theirs, they can be on many teams, and leaving is one edge.

14.3 Edges #

An edge says that a caller stands in a relation to a record, with a mode of access.

edge: E-71
  who: person:P-2201
  relation: coordinator
  mode: control
  on: L-9                       // the rec league
  grants: scheduleGames, recordScores
  where: not status is archived
  until: 2027-06-30
  by: E-12                      // the facility operator's edge

Edges are written and removed only through the border, as logged writes (chapter 8.5), and every one has a history.

14.4 Modes #

Each mode includes the ones below it. admin is full administration: it carries every menu item (14.6) on its records, but never the owner's key (14.1). It is never a way around the data either: must rules, archived records and the trust order still apply.

An owner holds admin over every record it owns, and the key besides.

Effective access. A caller's access to a record is worked out from every live edge the caller holds on the record or on any of its ancestors: the highest mode among them, and for control, every item they carry together. An edge whose where doesn't hold for the record, or whose until has passed, doesn't count.

Audiences (chapter 12.4) are read off edges: public is view for everyone; member is every person the owner has admitted (the signup contract grants their first edge, consume or view, on the owner's root); staff is anyone with a control or admin edge on any of the owner's records; owner is the owner. An audience says which projection a caller may read; which rows of it they see is the view's partition (chapter 12.6), so a control edge over one league admits its holder to staff views and shows them that league only.

A contract grants the consumer's edge. A contract that creates a record for a caller (an order, a booking, a submission) also writes that caller's edge on it, mode: consume with the contract's relation, under the running system's own edge as by. The owner owns the record; the consumer holds their part, and that is what "their own part" means above.

14.5 The grantor chain #

• You grant only what you hold. An edge's mode is at most its grantor's, its on is within the grantor's reach, and its grants are among the grantor's. An admin edge may grant anything up to admin; a control edge may grant only if it carries the grant item for what it grants.
• An edge is only as good as its grantor. An edge is live while the edge named in its by is live and still covers it. When an edge lapses or is removed, every edge granted under it lapses with it, down the chain. Nothing is deleted: lapsed edges stay in the history.
• Every chain ends at an owner. Following by from any edge reaches an owner grant in a finite number of steps. The owner holds the key at the top of every chain. The one exception is an emergency edge (14.13), which ends at platform and can't be granted onward.
• Upper admins stay above. The admin of a league can remove the edges inside a team that sits within it, including the captain's admin.

14.6 Permissions: menus, presets and narrowing #

A package declares what can be granted on its records:

permissions: facility
  menu:
    checkIn: run checkIn                         on: administered
    sellPasses: run sellPass, see unit::price
    scheduleGames: edit gameTime, run publishSchedule
    recordScores: edit score
    seeCost: see unit::cost
    decideArrivals: review arrivals
    archiveUnits: archive unit
    grantStaff: grant checkIn, sellPasses
  presets:
    frontDesk: checkIn, sellPasses               audience: staff
    coordinator: scheduleGames, recordScores     audience: staff
    seller: sellPasses, archiveUnits, seeCost    audience: member
  relations: operator, coordinator, captain, player, subscriber, follower only

• Relations are the names an edge's relation may take on the package's records. One marked only is relation-only: an edge with it has mode: none (14.10).
• Menu items are the only things that can be granted. Each is a verb with its targets, and optionally an on scope.
• The verbs: see (a value is shown), edit (a form may write it), run (a contract may start), review (queue items may be decided: vocabulary, arrivals, migrations, gated writes), archive and merge (chapter 1.12), apply (instructions, chapter 10.7), install (a package version, and the restamp that follows) and grant (making edges for the listed items). Targets are facets, classes, views, contracts and queues; * means all. The owner's powers (14.1) are not verbs and can't be granted.
• Scopes. on: owned means records the caller owns (14.1); on: administered means records the caller has admin on; on: relation player means records the caller holds that relation to; any other on is a condition over the record and caller. With no on, an item covers what the edge it is granted on covers.
• Presets are named bundles of items, each on an audience. A spec role (chapter 12.4) is a preset.
• À la carte. An edge's grants may mix presets and single items.
• Narrowing only. An edge's where adds conditions; it can never widen an item. A specific grant ("may edit price only on units in NM or VG condition") is an item plus a where.

A package MUST be refused at publish when an item names a verb, facet, class, view, contract or queue that doesn't exist, a preset names an item that doesn't exist, a preset grants anything its audience can't see, or a contract's relation isn't declared.

14.7 Gated edges #

An edge with gate: review gives access whose writes don't land. Each write made under it becomes a suggestion on the record (chapter 7.5), and the edge's reviewer accepts or denies it. Accepting writes the value with its original source; denying keeps it in the history as denied. Both are logged review writes (chapter 8.5).

A gate fits any access that should be watched before it is trusted: support from outside (14.8), a new member of staff, a community contributor, a utility on trial. Lifting the gate is a new version of the edge, logged like any other.

14.8 Across owners #

An owner MAY grant an edge to a caller of another owner: a peer-to-peer connection, with the other side proven by its domain's key (chapter 7.8). Support from the platform that hosts the owner is one such edge.

• Only the owner may grant it (14.1); no admin can.
• It SHOULD carry an until, and SHOULD carry gate: review unless the owner chooses otherwise.
• Every write the foreign caller makes is logged in the owner's log with that caller as by, so the owner can see everything it did as a view of its own log.
• Offer and take (chapter 7.8) remain the way owners share data. A cross-owner edge shares access, not data: the foreign caller works on the owner's records where they are.

14.9 Systems #

A system is a caller like a person. When a utility registers, it requests menu items, as an app requests scopes: the enricher asks for edit on the facets it fills, on: wears OpticalDisc. An admin who approves grants a control edge carrying exactly those items, gated while it is on trial if they choose. What every system may do is therefore a list anyone with view on the edge can read, and removing the edge cuts it off.

An AI agent that signs in is a system or acts for a person; either way it holds only the edges granted to it, and its writes carry its own by in the log.

14.10 Relations #

An edge with mode none is a relation only: following a team, watching a listing, favouriting a release.

• A relation never grants anything. Following gives a caller nothing they couldn't already see.
• You can follow only what you can view. If the caller's view lapses, the relation goes dormant, and it comes back if view returns. It is never removed silently.
• Relations drive feeds and notifications. A view MAY declare partition: relation follower (or any relation, owned or administered): each projection row carries its record and ancestors, the host hands the index the verified caller's edges, and the index serves a caller only the rows they stand in that relation to. The store decides the rows; the index only matches them (chapter 12.6.1).
• Paid subscriptions are contracts. A checkout that sells a season's stats creates an edge with mode: view, relation: subscriber and an until, and usually a follower relation beside it. The purchase decides access; the relation decides the feed.

14.11 The JSON form #

{
  "edge": "E-71",
  "who": "person:P-2201",
  "relation": "coordinator",
  "mode": "control",
  "on": "L-9",
  "grants": ["scheduleGames", "recordScores"],
  "where": "not status is archived",
  "until": "2027-06-30T00:00Z",
  "by": "E-12"
}

A gated edge adds "gate": "review" and, when it isn't the grantor, "reviewer". Permissions hold menu (name → {"verbs": {"run": ["checkIn"]}, "on": "administered"}), presets (name → {"items": […], "audience": "staff"}) and relations (name → {"only": true} or {}); ownership maps person to the kinds and classes a person may own.

14.12 Well-formed access #

A store MUST refuse a write that:

1. makes a within cycle;
2. grants an edge its grantor can't (14.5): a higher mode, a record outside the grantor's reach, or items the grantor doesn't hold or can't grant;
3. grants an edge to another owner's caller, unless the owner itself grants it (14.8);
4. names a preset or item the package doesn't declare;
5. gives grants to an edge whose mode isn't control, or a mode other than none to a relation the package declares as relation-only;
6. makes a person the owner of a record the package's ownership doesn't let a person own.

14.13 Emergency access #

A platform that hosts owners MAY reach an owner's records without the owner's grant, only through an emergency edge, and only for a legal order or a security incident that threatens the owner or others. It is the one edge not granted from inside the owner, so everything about it is stricter than any other.

• Not for lockouts. An owner who can't sign in has an authentication problem, which the host solves by account recovery (chapter 7.6). Recovery restores the owner's own access; it never needs an edge on their data.
• Declared in advance. A platform that can make emergency edges MUST publish its terms for them in its well-known file (chapter 11.7): who can approve, the longest they last, and how owners are told. An owner can always read them before trusting the platform, and a platform with no published terms can make none.
• Several people, none of them the requester. An emergency edge is created only when at least two approvers (or more, as the terms say) have each approved it, none of them the person asking. Each approval is signed with a key kept for this purpose alone, separate from everyday credentials, and given right after a fresh sign-in. No automation can approve.
• A stated reason. The edge carries its kind (legal or incident), the reason, and the reference of the order or incident.
• As narrow and short as possible. It is view, or control with only the items it names; never admin, never any owner power (14.1), never grant. It has an until no later than the terms allow, and it can't be extended: more time is a new edge with new approvals.
• Writes are gated. Any write under it lands as a suggestion with the owner as reviewer (14.7), unless a legal order requires the write itself, in which case the order's reference is on the write.
• Reads are logged too. Everything read under an emergency edge is written to the log, record by record, which no other edge requires.
• Witnessed on both sides. The edge, its approvals and every read and write are in the owner's signed log and, as a copy, in the platform's own log, each entry marked witnessed: true, which neither side can redact (chapter 8.5).
• The owner is told. At once, unless a legal order requires a delay. A delay is recorded with the order's reference and its end, and the owner is told when it ends.
• The owner can end it, unless it cites a legal order; then ending it is the order's matter, and the owner's attempt is recorded.
• Every emergency edge raises an alert at the platform and, once it may be told, at the owner.

{
  "edge": "E-9001",
  "who": "platform.example:staff/S-14",
  "relation": "emergency",
  "mode": "view",
  "on": "R-ROOT",
  "until": "2026-10-16T18:00Z",
  "emergency": {
    "kind": "incident",
    "reason": "Card-skimming script reported on the storefront",
    "reference": "INC-2026-114",
    "approvals": [ { "by": "platform.example:staff/S-02", "sig": "…" }, { "by": "platform.example:staff/S-31", "sig": "…" } ],
    "notify": "now"
  },
  "by": "platform"
}

A store MUST refuse an emergency edge that lacks the approvals its platform's published terms require, names the requester as an approver, carries admin, grant or an owner power, or outlasts the terms.

Edit on GitHub · Markdown