gnomonlearn
Docs/Graph/RFC-0042

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

TermMeaning
Predicate policyA rule of the form: “presence of a statement (subject, predicate, resource) grants permissionLevel to subject on resource.”
SubjectThe Resource (typically a user or service principal) on the LHS of an authorization relationship.
ResourceThe target Resource being accessed; the RHS.
Permission levelOne of read, write, admin, owner (RFC-0036 §5). Hierarchical bitmask.
Match modeHow the policy’s predicate field is matched against statement predicates: subtree (ltree <@) or exact (=).
ScopeOptional narrowing: resourceKind filters by Resource kind; resourceId filters to a single Resource.
when expressionAn optional policy expression evaluated at decision time; the policy only applies when the expression is true.
PresetA named handle (app.read, teams.member.read) that lets operations reference a policy by name.
PriorityAn 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

ModeComparisonExample
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:

resourceKindresourceIdApplies to
nullnullAll resources of all kinds
<kind>nullAll 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 session
  • subject, resource — the access decision context
  • now() — 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 validTo is 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 entryCompiled policy
member: readpredicate: <module-namespace>.member, permissionLevel: read, resourceKind: <module>.<template>, matchMode: subtree, priority: 65
admin: writepredicate: <module-namespace>.admin, permissionLevel: write, resourceKind: <module>.<template>, matchMode: subtree, priority: 80
owner: ownerpredicate: <module-namespace>.owner, permissionLevel: owner, resourceKind: <module>.<template>, matchMode: subtree, priority: 100
org.member: readpredicate: 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 ResourcePolicy is equivalent to a predicate_policy with no predicate (always-applies) scoped to resourceType.
  • A StatementPolicy is equivalent to a predicate_policy with predicate: <statementType> and matchMode: 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> }
FieldMeaning
requiresAuthIf true, the request MUST be authenticated (RFC-0048).
requiresRolesThe principal MUST have at least one of these named roles (legacy RBAC).
requiresPermissionsThe principal MUST have all named permissions (legacy ABAC-like).
policyA 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

  1. predicate and permissionLevel are required on every predicate policy (§3.1).
  2. resourceId without resourceKind MUST be rejected (§3.4, M42010).
  3. Permission accumulation is set-union; no “deny” rule (§4.2).
  4. Match mode subtree is the default; backends without ltree MUST simulate it (§4.4).
  5. The permission cache MUST be invalidated on any of the four trigger conditions (§5.2).
  6. Write-side permission decisions MUST re-evaluate inside the write transaction; cache reads alone are insufficient (§5.3, M42030).
  7. The permissions: shorthand on templates expands deterministically to predicate_policy objects with documented default priorities (§6).
  8. when expressions are memoized per-request, never across requests (§4.5).
  9. sameAs is informational only and MUST NOT influence runtime evaluation (§3.7).
  10. 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 fieldThis 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

  • when results 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.