# gizmodel/policy

The DAL's Policy. Grants on records live in one table, `grants`; record ancestry lives in one closure table, `ancestry`, which the writing transaction keeps with the record. Security.decide judges an actor over the grants on a target and its ancestors, read at one snapshot. A record that has no ancestry row has no access (default deny). Only Policy Operations write `grants`; they check the granting actor with `decide` first. A group is a record of type `group`: a grant on it makes its grantee a member, and a grant to Principal.group reaches every member. Every statement and condition here is a syntax tree: GizDB runs it, and render.giz prints it for a SQL store.

```gizlang
import * as Policy from "gizmodel/policy";
```

## Types

### `AncestryRow`

```gizlang
type AncestryRow = { @Model.Key descendant: string; @Model.Key ancestor: string; depth: i64; }
```

The ancestry of a placed record: each ancestor and the depth below it.

- `descendant`: `string`
- `ancestor`: `string`
- `depth`: `i64`

### `Write`

```gizlang
type Write = { commands: Vec<Statement>; params: Vec<Value>; rows: Option<i64>; touched: Vec<Touch>; }
```

Statements (syntax trees, as Query and Model build them) and the parameters $1.. they share. When `rows` is set, the
first statement must change exactly that many rows, else the transaction is a conflict. Db.write runs a Write.

- `commands`: `Vec<M151.Statement>`
- `params`: `Vec<M143.Value>`
- `rows`: `_gizlang_sdk_core.Option<i64>`
- `touched`: `Vec<M134.Touch>`

### `Touch`

```gizlang
type Touch = { table: string; key: string; }
```

A row a Write changes (`key` "": any row of the table), for the live views of a store that has no change log of its own.

- `table`: `string`
- `key`: `string`

### `Kept`

```gizlang
type Kept = { version: string; held: Map<string, Vec<Security.Grant>>; reached: Map<string, Reached>; }
```

What decide read in one version of a source's data (Source.version), by what it asked: the groups a person is in
(memberships) and a target's ancestry with the grants on it. A request asks the same Policy questions many times (each
count of a page asks for its table), and each read the grants again: a third of a todo page's CPU (2026-11-08).
Another version forgets them all: a grant, a revoke or a rollback is another version, so a kept read never outlives
its data (DB-SCOPE-REVOKE). The decision itself is made again each time, at its own time (an expiry).

- `version`: `string`
- `held`: `_gizlang_sdk_collections.Map<string, Vec<gizlang_security.Grant>>`
- `reached`: `_gizlang_sdk_collections.Map<string, M134.Reached>`

## Functions

### `shapes`

```gizlang
function shapes(): Vec<Model.Shape>
```

The two tables, made once with the database (Data.install).

Effects: fail, read, write, console, io, alloc.

### `tables`

```gizlang
function tables(): Vec<string>
```

Tables whose committed writes can change a record's access without changing that record.

Effects: fail, read, write, console, io, alloc.

### `place`

```gizlang
function place(nodes: Vec<Security.ResourceRef>, parent: Option<Security.ResourceRef>): Write throws DbError
```

The statements that place new records (at least one) under `parent` (none for a root). Run them in the transaction
that inserts the records. A parent that has no ancestry row passes nothing on.

Effects: fail, alloc.

### `root`

```gizlang
function root(ref: Security.ResourceRef): Write
```

The statement that places the record REF as a root, again or not: a provisioned table (Gate.provision). Placed again,
it writes nothing (a record's own row has depth 0), so an app starts on a store that takes no writes (one at its quota).

Effects: fail, alloc.

### `move`

```gizlang
function move(node: Security.ResourceRef, parent: Security.ResourceRef): Write throws DbError
```

Statements that move a placed record, with everything under it, to `parent`.
A move under the record itself, or of a record that is not placed, rolls
the transaction back (ErrorKind.conflict).

Effects: fail, alloc.

### `remove`

```gizlang
function remove(node: Security.ResourceRef): Write throws DbError
```

Statements that remove a record and everything under it from Policy: their
grants and their ancestry. Run them with the record's delete.

Effects: fail, alloc.

### `grant`

```gizlang
function grant(principal: Security.Principal, target: Security.ResourceRef, role: Security.Role, expires: i64, now: i64, by: Security.Principal): Write throws DbError
```

A grant of `role` on `target` until `expires` (0: no end), replacing an
earlier grant to the same principal.

Effects: fail, alloc.

### `revoke`

```gizlang
function revoke(principal: Security.Principal, target: Security.ResourceRef): Write throws DbError
```

The write that removes the grant of PRINCIPAL on TARGET.

Effects: fail, alloc.

### `kept`

```gizlang
function kept(): Kept
```

Nothing kept yet: one for each request (gate.giz Scope).

Effects: fail, alloc.

### `decide`

```gizlang
function decide(source: Source, actor: Security.Principal, target: Security.ResourceRef, needed: Security.Role, now: i64, kept: Option<Ref<Kept>> = undefined): Security.Decision throws DbError
```

The actor's decision on `target` for the `needed` role at `now`: the target's
ancestry and the grants of the actor, of an agent's person and of their groups
on it, in one snapshot. With KEPT, the reads of this version of the data are kept there.

Effects: fail, read, write, console, io, alloc.

### `commands`

```gizlang
function commands(w: Write): Vec<Statement> throws DbError
```

The statements of `w` as the GizDB engine runs them (Connection.write, Transaction.write): the first one guarded when `rows` is set.

Effects: fail, alloc.

### `commandsIn`

```gizlang
function commandsIn(w: Write, schema: string): Vec<Statement> throws DbError
```

The statements of W, each placed in SCHEMA ("" leaves them as they are): a write there is one INSERT, UPDATE or
DELETE of one table of it, so it reaches nothing outside the schema unseen.

Effects: fail, alloc.

### `oneTable`

```gizlang
function oneTable(s: Statement, schema: string): bool throws DbError
```

Whether the write S names one table only and no schema of its own (no FROM, USING, INSERT ... SELECT or
subquery): the writes a records schema takes.

Effects: fail, alloc.

### `groups`

```gizlang
function groups(source: Source, person: Security.Principal, now: i64): Vec<Security.ResourceRef> throws DbError
```

The groups that PERSON is a member of at NOW: its unexpired grants on group references (a role of an app is its group).

Effects: fail, read, write, console, io, alloc.

### `reaches`

```gizlang
function reaches(source: Source, actor: Security.Principal, needed: Security.Role, now: i64, row: Expr): Tree.Expression<bool> throws DbError
```

The condition that a grant of at least `needed` reaches the record that the text expression `row` (a SPACE/TYPE/KEY
reference) names, on the record or on an ancestor: `decide` for many rows at once, so a query selects only what the
actor may read. An agent needs its own grant and its person's grant, under its ceiling; a group does not act.

Effects: fail, read, write, console, io, alloc.

## Constants

### `DEPTH`

```gizlang
const DEPTH: i64 = 32
```

The most levels a record inherits grants through (its own row is level 0).

