RFC-0042 · Predicate Policy and Authorization
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
| Status | Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release. |
|---|
View the generated reference catalog →
Read design questions and decisions →
Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.
1. Purpose
A predicate policy is the canonical Gnomon authorization rule. It says: “if a subject has a statement with this predicate pointing to a resource, the subject is granted this permission level on that resource.”
This composition — graph relations as authorization rules — is the load-bearing distinguishing feature of Gnomon’s auth model. It is more expressive than RBAC (because grants follow the actual graph topology) and more concrete than ABAC (because policies attach to declared predicates with declared scopes, not to opaque attributes).
This RFC promotes the legacy predicate_policy module object (/Volumes/Workspace/savvi-studio-full/packages/graph-module-model/model/objects/predicate-policy.ts) to a first-class normative declaration in the Gnomon framework. It specifies the policy declaration shape, the runtime evaluation semantics, the permission bitmask (RFC-0036 §5) consumption, the priority/match-mode/scope ordering rules, the when policy-expression integration, and the presets mechanism for procedure authorization.
This RFC does NOT redefine the language-level policy declaration (RFC-0008 §6.6). That remains the higher-level expression of intent; this RFC is the runtime representation that policies compile down to.
2. Definitions
| Term | Meaning |
|---|---|
| Predicate policy | A rule of the form: “presence of a statement (subject, predicate, resource) grants permissionLevel to subject on resource.” |
| Subject | The Resource (typically a user or service principal) on the LHS of an authorization relationship. |
| Resource | The target Resource being accessed; the RHS. |
| Permission level | One of read, write, admin, owner (RFC-0036 §5). Hierarchical bitmask. |
| Match mode | How the policy’s predicate field is matched against statement predicates: subtree (ltree <@) or exact (=). |
| Scope | Optional narrowing: resourceKind filters by Resource kind; resourceId filters to a single Resource. |
when expression | An optional policy expression evaluated at decision time; the policy only applies when the expression is true. |
| Preset | A named handle (app.read, teams.member.read) that lets operations reference a policy by name. |
| Priority | An integer 0–100 that breaks ties when multiple policies match the same (subject, resource) pair. |
3. Predicate Policy Declaration
A predicate_policy object in a module manifest (RFC-0040 §9) declares one rule:
<name>:
type: predicate_policy
predicate: <ltree-path> # required
permissionLevel: read | write | admin | owner # required
resourceKind: <ltree-path>? # scope to a kind
resourceId: <string>? # scope to a single resource
description: <text>?
sameAs: <CURIE>? # ontology alignment
isActive: boolean (default true)
priority: integer 0..100 (default 0)
matchMode: exact | subtree (default subtree)
preset: <DnsLabel>? # named handle
when: <policy-expression>? # conditional grant
3.1 Required fields
predicate and permissionLevel are required. All others are optional with declared defaults.
A policy with neither resourceKind nor resourceId applies to all resources globally; this is intentional and is how legacy policies like member_of (read on all org-membership resources) are expressed.
3.2 Permission level semantics
The four levels form a hierarchical bitmask (RFC-0036 §5):
read = 0b0001 = 1
write = 0b0011 = 3
admin = 0b0111 = 7
owner = 0b1111 = 15
Granting write automatically grants read. Granting admin automatically grants read and write. Granting owner (the legacy “Grant” level) grants all four.
Standard priority conventions (matching the legacy seed data):
- owner-level: ~100
- admin-level: ~90
- write-level: ~80
- read-level: ~65–70
3.3 Match mode
| Mode | Comparison | Example |
|---|---|---|
subtree (default) | ltree <@ (descendant or equal) | Policy predicate org matches statement predicates org, org.member, org.admin, org.billing.manager. |
exact | = | Policy predicate org.member matches only statements whose predicate is exactly org.member. |
Subtree mode is the default because it is what legacy authorization rules need: declare a rule once at org and have it apply to all org.* predicates.
3.4 Scoping
resourceKind and resourceId narrow the policy:
resourceKind | resourceId | Applies to |
|---|---|---|
null | null | All resources of all kinds |
<kind> | null | All resources of kind <kind> |
null | <id> | (invalid — resourceId requires resourceKind) |
<kind> | <id> | The single resource (kind, externalId=<id>) |
The combination resourceId without resourceKind MUST produce M42010.
3.5 when expressions
The when field, when present, is a policy expression (defined in auth-model’s PolicyExpressionSchema) evaluated at decision time. The policy applies only when the expression evaluates to true.
The expression has access to:
principal— the current principal (RFC-0048)session— the active sessionsubject,resource— the access decision contextnow()— the current instant
when is the conditional-grant mechanism that lets a single policy declaration cover time-windowed grants, role-conditioned access, etc.
3.6 Presets
A preset is a named handle that operations (RFC-0043) can reference for authorization metadata:
- name: app-read
type: predicate_policy
preset: app.read
predicate: app.member
permissionLevel: read
priority: 65
- name: app-admin
type: predicate_policy
preset: app.admin
predicate: app.admin
permissionLevel: admin
priority: 90
Operations declare authorization.policy: { preset: app.read } (RFC-0043) which compiles to the same evaluation as the policy itself, but is referenceable across modules without re-declaring.
3.7 sameAs ontology alignment
sameAs links the policy’s predicate to an external ontology term (CURIE or full URI):
- name: org-membership
type: predicate_policy
predicate: org.member
permissionLevel: read
priority: 65
sameAs: schema:memberOf
This is informational at runtime and consumed by tooling, federation, and SDO-aware introspection (RFC-0010 §9 Knowledge Index).
4. Runtime Evaluation
4.1 Permission check entry point
The runtime evaluates permission via the backend’s PermissionService (RFC-0037 §4.3):
backend.permissions.read({
type: GetPermission,
params: {
subjectId, subjectType,
resourceId, resourceKind | resourceType
}
}) → permissionBits: number
This entry point is what operation handlers, query authorization gates, and the graph client call to evaluate access.
4.2 Evaluation algorithm
For a request (subject, resource, requiredLevel):
1. Find all active policies (isActive: true) whose `resourceKind` and
`resourceId` scope matches the resource.
2. For each such policy, find statements where:
subject = <subject>
predicate matches policy.predicate via policy.matchMode
object = resource (or resource is in the same kind, depending on scope)
3. For matching statements, evaluate policy.when (if present).
4. If any matching policy survives evaluation, accumulate its permissionLevel
bits into the subject's effective permission bits for this resource.
5. Return the bitwise-OR of all granted permission bits.
The evaluation is set-union: matching grants accumulate. There is no “deny” rule; absence of a matching grant is the denial.
4.3 Priority and conflict resolution
Priority does NOT affect set-union accumulation directly; it affects explanation and caching. When the runtime materializes a permission cache entry (RFC-0036 §6.2), it records which policies contributed (derivedFrom), ordered by descending priority.
Two policies that grant the same level on the same resource via the same statement are deduplicated. Two policies that grant different levels are accumulated bitwise.
4.4 Match-mode evaluation
For matchMode: subtree:
statement.predicate <@ policy.predicate (ltree descendant-or-equal)
For matchMode: exact:
statement.predicate = policy.predicate
Backends that do not support ltree natively MUST implement subtree matching in application code: maintain a prefix index over predicate paths and check statement.predicate.startsWith(policy.predicate + ".") plus equality.
4.5 when evaluation context
The when expression evaluates against:
{
principal: { id, displayName, scopes, tenantId, ... }
session: { issuedAt, expiresAt, ... }
subject: { id, kind, data, ... }
resource: { id, kind, externalId, data, ... }
now: <Instant>
}
The expression language is defined in auth-model’s PolicyExpressionSchema. Implementations MUST cache when-expression results within a single request scope (memoization by stable hash of inputs); they MUST NOT cache across requests because principals and times change.
5. Permission Cache
5.1 Cache shape
The runtime materializes permission decisions into a cache (RFC-0036 §6.2):
PermissionCache {
subjectId, subjectKind,
resourceId, resourceKind,
permissionBits,
derivedFrom: [<policy ids ordered by priority>]
computedAt, expiresAt, isValid
}
5.2 Invalidation
The cache MUST be invalidated when:
- A new statement is created whose predicate matches any active policy.
- An existing statement’s
validTois set (invalidate via RFC-0037 §4.2). - A policy is created, modified, or deactivated.
- The subject or resource is soft-deleted.
Invalidation may be eager (write-through) or lazy (mark isValid: false, recompute on next read). Backends MUST document their choice.
5.3 Authoritative reads
Permission queries MUST NOT trust the cache for write-side decisions. When a write depends on a permission check (e.g., update(id, ...) requires write access), the runtime MUST re-evaluate the policy chain inside the write transaction; reading from the cache without re-evaluation is M42030 (defect).
6. Templates and Permissions Shorthand
Templates (RFC-0039 §3.4) MAY declare a permissions: shorthand:
permissions:
member: read
admin: write
owner: owner
org.member: read # qualified: used as-is
The compiler (RFC-0040 §11 / RFC-0044) expands each entry into a predicate_policy module object:
| Shorthand entry | Compiled policy |
|---|---|
member: read | predicate: <module-namespace>.member, permissionLevel: read, resourceKind: <module>.<template>, matchMode: subtree, priority: 65 |
admin: write | predicate: <module-namespace>.admin, permissionLevel: write, resourceKind: <module>.<template>, matchMode: subtree, priority: 80 |
owner: owner | predicate: <module-namespace>.owner, permissionLevel: owner, resourceKind: <module>.<template>, matchMode: subtree, priority: 100 |
org.member: read | predicate: org.member, permissionLevel: read, resourceKind: <module>.<template>, matchMode: subtree, priority: 65 |
Unqualified names are prefixed with the declaring module’s namespace; qualified names are used as-is (must contain a . or :).
Default priorities follow the convention: owner=100, admin=90, write=80, read=65 (RFC-0036 §5 conventions).
7. Resource and Statement Policies (Legacy)
RFC-0036 §6.3 also defines ResourcePolicy and StatementPolicy — direct grants on resources or statement types. These are degenerate cases of predicate policy:
- A
ResourcePolicyis equivalent to apredicate_policywith nopredicate(always-applies) scoped toresourceType. - A
StatementPolicyis equivalent to apredicate_policywithpredicate: <statementType>andmatchMode: exact.
Implementations MAY treat these as a separate evaluation path or unify under predicate policy evaluation. The data model (RFC-0036 §6.3) preserves the legacy shape; this RFC’s evaluation algorithm (§4.2) covers both.
New policy authoring SHOULD use predicate_policy for clarity; resource and statement policies are preserved for migration of legacy schema.
8. Authorization on API Surfaces
The API declaration (RFC-0033) exposes operations to external callers. Authorization on those operations integrates with predicate policies:
operation:
authorization:
requiresAuth: true
requiresRoles: [admin, manager]
requiresPermissions: [edit, delete]
policy: { preset: <preset-name> }
| Field | Meaning |
|---|---|
requiresAuth | If true, the request MUST be authenticated (RFC-0048). |
requiresRoles | The principal MUST have at least one of these named roles (legacy RBAC). |
requiresPermissions | The principal MUST have all named permissions (legacy ABAC-like). |
policy | A reference to a predicate-policy preset, evaluated against the operation’s subject/resource. |
The combination is conjunctive: ALL declared requirements must be satisfied. The policy evaluation runs the algorithm in §4.2; the requiresRoles / requiresPermissions checks are simpler attribute lookups against the principal.
This RFC specifies the predicate-policy evaluation; the role and permission attribute model is defined in RFC-0048 §principal attributes.
9. Invariants
predicateandpermissionLevelare required on every predicate policy (§3.1).resourceIdwithoutresourceKindMUST be rejected (§3.4, M42010).- Permission accumulation is set-union; no “deny” rule (§4.2).
- Match mode
subtreeis the default; backends without ltree MUST simulate it (§4.4). - The permission cache MUST be invalidated on any of the four trigger conditions (§5.2).
- Write-side permission decisions MUST re-evaluate inside the write transaction; cache reads alone are insufficient (§5.3, M42030).
- The
permissions:shorthand on templates expands deterministically topredicate_policyobjects with documented default priorities (§6). whenexpressions are memoized per-request, never across requests (§4.5).sameAsis informational only and MUST NOT influence runtime evaluation (§3.7).- Presets are referenceable across modules; preset names MUST be unique within a runtime (M42040).
10. Compatibility and Migration
10.1 From legacy predicate_policy
This RFC is a faithful codification of the legacy schema at /Volumes/Workspace/savvi-studio-full/packages/graph-module-model/model/objects/predicate-policy.ts:
| Legacy field | This RFC |
|---|---|
predicate | §3 |
permissionLevel | §3 + §3.2 |
resourceKind | §3.4 |
resourceId | §3.4 |
description | §3 |
sameAs | §3.7 |
isActive | §3 (default true) |
priority | §3 + §4.3 |
matchMode | §3.3 |
preset | §3.6 |
when | §3.5 + §4.5 |
The mapping is direct. Existing legacy policies (e.g., the four bootstrap policies in core.auth/module.gnm) install unchanged.
10.2 From legacy ResourcePolicy / StatementPolicy
Existing direct-grant policies are preserved (§7). Migration to predicate-policy form is RECOMMENDED but not required. Both forms participate in the §4.2 evaluation.
10.3 Behavior changes
whenresults are memoized per-request. Legacy code does not specify caching; this RFC requires within-request memoization.- Write-side decisions MUST re-evaluate. Legacy code permits cache reads on writes; this RFC bans it (M42030).
- Preset names are runtime-globally unique. Legacy code does not enforce uniqueness; this RFC requires it (M42040).
Diagnostics
The diagnostic catalog for this RFC is authored in the structured Lean module and
rendered in reference catalog § Diagnostics. Inline mentions in
the prose above (e.g., “rejected with MNNxxx”) cross-link to the catalog
at render time.
Linked References
The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.