gnomonlearn
Docs/RFC-0042/Reference catalog

RFC-0042 · Reference catalog

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.

← Read the authored RFC

Generated reference catalog. This page renders structured Lean data for RFC-0042: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in RFC-0042.

This page is generated from the lean/Gnomon/Spec/ module for RFC-0042. Edit that source and regenerate this catalog.


Title: Predicate Policy and Authorization
Status: draft
Owners: Graph Platform, Security
Diagnostic range: M42000-M42099

Depends on: RFC-0001, RFC-0006, RFC-0007, RFC-0036, RFC-0037, RFC-0038, RFC-0039, RFC-0040
Extended by: RFC-0043, RFC-0048

Proof citations in source: 13 / 13. Standalone proof verification is pending.


Definitions

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

Diagnostics

CodeSeverityDescription
M42010ErrorresourceId declared without resourceKind — scope is invalid
M42011Errorpriority outside the legal 0..100 range
M42012ErrorpermissionLevel is not one of read, write, admin, owner
M42013ErrormatchMode is not one of exact, subtree
M42020Errorpredicate references a path that is not declared by any installed module (orphan predicate reference)
M42021Warningpredicate is declared but no statements use it; policy is dormant
M42030ErrorPermission cache used for write-side authorization decision; defect — re-evaluation required
M42031WarningPermission cache invalidation skipped a transitively-affected entry; cache may be stale until next refresh
M42040ErrorPreset name collision: two predicate policies declare the same preset name
M42041WarningPreset declared but never referenced by any operation
M42050Errorwhen expression failed to evaluate (parse error, undefined reference, type mismatch)
M42051Warningwhen expression has high evaluation cost; consider memoization or simpler form
M42060ErrorsameAs value is not a syntactically-valid CURIE or URI
M42070ErrorSubtree match attempted on a backend without ltree support and no fallback path index configured

Dependency neighborhood

graph LR
  nRFC_0042["RFC-0042"]
  nRFC_0001["RFC-0001"]
  nRFC_0042 --> nRFC_0001
  nRFC_0006["RFC-0006"]
  nRFC_0042 --> nRFC_0006
  nRFC_0007["RFC-0007"]
  nRFC_0042 --> nRFC_0007
  nRFC_0036["RFC-0036"]
  nRFC_0042 --> nRFC_0036
  nRFC_0037["RFC-0037"]
  nRFC_0042 --> nRFC_0037
  nRFC_0038["RFC-0038"]
  nRFC_0042 --> nRFC_0038
  nRFC_0039["RFC-0039"]
  nRFC_0042 --> nRFC_0039
  nRFC_0040["RFC-0040"]
  nRFC_0042 --> nRFC_0040
  nRFC_0043["RFC-0043"]
  nRFC_0043 --> nRFC_0042
  nRFC_0048["RFC-0048"]
  nRFC_0048 --> nRFC_0042

Invariants

  1. A predicate policy with resourceId but no resourceKind MUST be rejected with M42010. (enforced by: install-time)
  2. Every predicate policy MUST declare both predicate and permissionLevel. (enforced by: install-time)
  3. Permission accumulation across matching policies is set-union with no deny rule; absence of grant is denial. (enforced by: runtime)
  4. Preset names MUST be unique within a runtime; collisions are M42040. (enforced by: install-time)
  5. Subtree matching is the default match mode and backends without ltree MUST simulate it via prefix index. (enforced by: runtime)
  6. The permission cache MUST be invalidated on statement create, validTo set, policy change, or subject/resource soft-delete. (enforced by: runtime)
  7. The sameAs alignment is informational and MUST NOT influence runtime evaluation. (enforced by: runtime)
  8. The templates permissions: shorthand expands deterministically to predicate_policy objects with documented default priorities. (enforced by: compile-time)
  9. When-expression results MUST be memoized within a single request and MUST NOT be cached across requests. (enforced by: runtime)
  10. Write-side authorization decisions MUST re-evaluate inside the write transaction; cache reads alone are M42030. (enforced by: runtime)

Normative Statements

Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.

Authorization on API Surfaces

  1. MUST — If requiresAuth is true, the request must be authenticated (proof citation: rfc0042_b3_grounded; verification pending)
  2. MUST — The principal must have all named requiresPermissions (proof citation: rfc0042_b25_grounded; verification pending)
  3. MUST — The principal must have at least one of the declared requiresRoles (proof citation: rfc0042_b21_grounded; verification pending)

Compatibility and Migration

  1. RECOMMENDED — Migration of legacy ResourcePolicy/StatementPolicy to predicate-policy form is recommended but not required

Invariants

  1. MUST — Permission cache must be invalidated on any of the four trigger conditions (proof citation: rfc0042_b29_grounded; verification pending)
  2. MUST — Preset names must be unique within a runtime
  3. MUST — Write-side permission decisions must re-evaluate inside the write transaction (proof citation: rfc0042_b9_grounded; verification pending)
  4. MUST — resourceId without resourceKind must be rejected (proof citation: rfc0042_b31_grounded; verification pending)
  5. MUST_NOT — sameAs must not influence runtime evaluation

Permission Cache

  1. MUST — Backends must document whether invalidation is eager or lazy
  2. MUST_NOT — Permission queries must not trust the cache for write-side decisions (proof citation: rfc0042_b11_grounded; verification pending)
  3. MUST — The permission cache must be invalidated on the four documented trigger conditions (proof citation: rfc0042_b5_grounded; verification pending)
  4. MUST — Writes depending on a permission check must re-evaluate the policy chain inside the write transaction (proof citation: rfc0042_b23_grounded; verification pending)

Predicate Policy Declaration

  1. MUST — predicate and permissionLevel are required on every policy
  2. MUST — resourceId without resourceKind must produce M42010 (proof citation: rfc0042_b19_grounded; verification pending)

Resource and Statement Policies (Legacy)

  1. MAY — Implementations may treat resource and statement policies as a separate path or unify under predicate policy evaluation (proof citation: rfc0042_b13_grounded; verification pending)
  2. SHOULD — New policy authoring should use predicate_policy for clarity

Runtime Evaluation

  1. MUST — Backends without native ltree must implement subtree matching via prefix index and equality
  2. MUST_NOT — Implementations must not cache when-expression results across requests (proof citation: rfc0042_b0_grounded; verification pending)
  3. MUST — when-expression results must be memoized within a single request scope

Templates and Permissions Shorthand

  1. MAY — Templates may declare a permissions shorthand that expands to predicate_policy objects (proof citation: rfc0042_b17_grounded; verification pending)

Linked References

DirectionTarget
Depends onRFC-0001
Depends onRFC-0006
Depends onRFC-0007
Depends onRFC-0036
Depends onRFC-0037
Depends onRFC-0038
Depends onRFC-0039
Depends onRFC-0040
Extended byRFC-0043
Extended byRFC-0048