RFC-0036 · 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.
Generated reference catalog. This page renders structured Lean data for RFC-0036: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0036.This page is generated from the
lean/Gnomon/Spec/module for RFC-0036. Edit that source and regenerate this catalog.
Title: Graph Data Model
Status: draft
Owners: Graph Platform, Storage
Diagnostic range: M36000-M36099
Depends on: RFC-0006, RFC-0007
Extended by: RFC-0037, RFC-0038, RFC-0039, RFC-0042, RFC-0049, RFC-0050, RFC-0051, RFC-0052, RFC-0053
Proof citations in source: 28 / 28. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| Bitemporal edge | A Statement with validFrom/validTo columns capturing when the asserted relation was true in the world. |
| External ID | A caller-supplied stable identifier for a Resource, scoped within its kind, used for upsert and idempotent provisioning. |
| Graph entity | Any persisted record in the graph: Resource, Statement, Predicate, Workspace, PermissionCache, ResourcePolicy, StatementPolicy, or ExternalLink. |
| ID | A stable, monotonically-allocated identifier of type bigint, assigned by the storage backend at creation time. |
| Kind | A string label that classifies a Resource, conventionally an ltree path (e.g., identity.user, products.item). |
| Permission bits | A SMALLINT bitmask encoding a permission level (Read=1, Write=3, Admin=7, Grant=15). |
| Permission cache | A materialized projection of effective permissions per (subject, resource) pair. |
| Predicate | A named relation type, identified globally by its ltree path (e.g., org.member, team.owner). |
| Soft delete | Logical deletion via setting deletedAt; the row remains queryable for audit and bitemporal reads. |
| Statement | A typed triple (subjectId, predicateId, objectId) that asserts a relation between two Resources. |
| Workspace | A top-level container Resource that scopes a tenant or environment partition. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M36010 | Error | Statement validFrom > validTo — interval is invalid |
M36011 | Error | Statement [validFrom, validTo) overlaps an existing Statement on the same (subjectId, predicateId, objectId) triple |
M36020 | Error | Predicate path already exists — paths must be globally unique |
M36021 | Error | Attempt to delete a Predicate that is referenced by one or more Statements |
M36030 | Error | permissionBits value is outside the canonical set {0, 1, 3, 7, 15} |
M36040 | Error | data field contains a literal null value — null is prohibited |
M36050 | Error | Insert references a soft-deleted Resource as subjectId or objectId |
M36060 | Error | (kind, externalId) pair already exists — Resource external IDs must be unique within kind |
M36061 | Error | externalId reuse attempted: this externalId was previously assigned to a different (now-deleted) Resource within this kind |
M36070 | Warning | Statement insert without predicateId AND without predicate — backend cannot resolve the relation |
M36080 | Warning | Backend internally normalized a permissionBits value to the canonical set; review the upstream source |
Dependency neighborhood
graph LR
nRFC_0036["RFC-0036"]
nRFC_0006["RFC-0006"]
nRFC_0036 --> nRFC_0006
nRFC_0007["RFC-0007"]
nRFC_0036 --> nRFC_0007
nRFC_0037["RFC-0037"]
nRFC_0037 --> nRFC_0036
nRFC_0038["RFC-0038"]
nRFC_0038 --> nRFC_0036
nRFC_0039["RFC-0039"]
nRFC_0039 --> nRFC_0036
nRFC_0042["RFC-0042"]
nRFC_0042 --> nRFC_0036
nRFC_0049["RFC-0049"]
nRFC_0049 --> nRFC_0036
nRFC_0050["RFC-0050"]
nRFC_0050 --> nRFC_0036
nRFC_0051["RFC-0051"]
nRFC_0051 --> nRFC_0036
nRFC_0052["RFC-0052"]
nRFC_0052 --> nRFC_0036
nRFC_0053["RFC-0053"]
nRFC_0053 --> nRFC_0036
Invariants
- An externalId must not be reassigned to a different Resource after deletion of the original. (enforced by: runtime)
- Every graph entity has a stable, monotonic, backend-allocated bigint id globally unique across entity types. (enforced by: runtime)
- Multiple Statements on the same (subjectId, predicateId, objectId) triple must have disjoint validFrom intervals; overlaps are rejected with M36011. (enforced by: runtime)
- New Statements must not reference soft-deleted Resources as subjectId or objectId; rejected with M36050. (enforced by: runtime)
- Only the db.graph platform module declares Resource and Statement; application modules must not redefine them or write to graph.resource/graph.statement directly. (enforced by: compile-time + runtime + RLS)
- Persisted data must encode bigint values as decimal strings since JSON cannot represent bigint natively. (enforced by: runtime)
- Predicate paths MUST be globally unique across the runtime (M36020). (enforced by: install-time)
- Predicate.path must be a valid ltree path and globally unique; duplicates are rejected with M36020. (enforced by: runtime)
- Predicates must not be deleted while any Statement references them. (enforced by: runtime)
- Resource.data must be a JSON-serializable object and the backend must not silently drop unknown keys. (enforced by: runtime)
- Resource.kind MUST be present and non-empty. (enforced by: runtime)
- Statement [validFrom, validTo) is half-open; validFrom > validTo must be rejected with M36010. (enforced by: runtime)
- Statement subjectId and objectId must refer to existing, non-deleted Resources at insert time. (enforced by: runtime)
- Statement.predicateId and Statement.predicate must be kept consistent and exactly one is required at write time. (enforced by: runtime)
- Statements must not be silently deduplicated by the backend; the client controls upsert semantics. (enforced by: runtime)
- The PermissionCache is non-authoritative; writes that depend on a permission decision must re-evaluate or hold a write-side lock. (enforced by: runtime)
- The PermissionCache must be invalidated whenever a policy or relevant Statement is mutated. (enforced by: runtime)
- The pair (kind, externalId) MUST be unique within the backend across Resources. (enforced by: runtime)
- The permission cache MUST be invalidated on statement create, validTo set, policy change, or subject/resource soft-delete. (enforced by: runtime)
- data fields must not contain literal null values; such inserts are rejected with M36040. (enforced by: runtime)
- permissionBits values outside the canonical set {0,1,3,7,15} must be treated as a defect (M36030) and not silently normalized. (enforced by: runtime)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Auxiliary Entity Types
- SHOULD — All Resources and Statements within a runtime SHOULD be reachable from at least one Workspace. (proof citation:
rfc0036_workspace_reachability; verification pending) - MUST — The PermissionCache MUST be invalidated whenever a policy or relevant Statement is mutated. (proof citation:
rfc0036_permission_cache_invalidated_on_mutation; verification pending) - MUST — Writes that depend on a permission decision MUST re-evaluate or hold a write-side lock rather than rely on the cache. (proof citation:
rfc0036_writes_re_evaluate_or_lock; verification pending)
Bitemporality
- MUST — Implementations MUST support asOf(t), validAt(t), and combined asOf(t_sys).validAt(t_val) queries. (proof citation:
rfc0036_supports_bitemporal_query_modes; verification pending)
Core Entity Types
- MUST — Exactly one of predicateId and predicate MUST be supplied at Statement write time. (proof citation:
rfc0036_write_predicate_xor; verification pending) - MUST — Overlapping validFrom intervals on the same (subjectId, predicateId, objectId) triple MUST be rejected with M36011. (proof citation:
rfc0036_no_overlapping_triple_intervals; verification pending) - MUST — Predicate path MUST be a valid ltree path and globally unique; duplicates rejected with M36020. (proof citation:
rfc0036_predicate_path_valid_and_unique; verification pending) - MUST_NOT — Predicates MUST NOT be deleted while any Statement references them. (proof citation:
rfc0036_predicate_not_deletable_while_referenced; verification pending) - MUST — Resource kind MUST be present and non-empty. (proof citation:
rfc0036_kind_present_nonempty; verification pending) - MUST — Statement subjectId and objectId MUST refer to existing, non-deleted Resources at insert time. (proof citation:
rfc0036_statement_endpoints_alive_at_insert; verification pending) - MUST — Statement validFrom > validTo MUST be rejected with M36010. (proof citation:
rfc0036_validfrom_le_validto; verification pending) - MUST_NOT — Statements MUST NOT be silently deduplicated by the backend. (proof citation:
rfc0036_no_silent_dedup; verification pending) - MUST_NOT — The backend MUST NOT silently drop unknown keys in data. (proof citation:
rfc0036_no_silent_drop_unknown_keys; verification pending)
Identity Model
- MUST_NOT — A Resource and a Statement MUST NOT share an id. (proof citation:
rfc0036_resource_statement_disjoint_ids; verification pending) - MUST_NOT — An externalId MUST NOT be reassigned to a different Resource after deletion of the original. (proof citation:
rfc0036_externalid_no_reassignment; verification pending) - MUST — Backends MUST treat the kind field as opaque text. (proof citation:
rfc0036_kind_treated_as_opaque; verification pending) - SHOULD — Backends SHOULD index kind for prefix and equality lookups.
- MUST — Both predicateId and predicate MUST be present on a persisted Statement and the backend MUST keep them consistent. (proof citation:
rfc0036_persisted_predicate_both_forms; verification pending) - MUST — The pair (kind, externalId) MUST be unique within the backend. (proof citation:
rfc0036_kind_externalid_unique; verification pending)
Permission Bits
- MUST_NOT — Out-of-range permissionBits MUST NOT be silently normalized. (proof citation:
rfc0036_no_silent_permission_normalization; verification pending) - MUST — Permission checks MUST use bitwise comparison: (current & required) === required. (proof citation:
rfc0036_permission_check_canonical; verification pending) - MUST — The runtime MUST treat permissionBits values outside {0, 1, 3, 7, 15} as a defect (M36030). (proof citation:
rfc0036_permission_bits_out_of_range_is_defect; verification pending)
Purpose
- MUST — Every Gnomon-conformant graph backend MUST implement these shapes exactly. (proof citation:
rfc0036_conformance_implements_all_shapes; verification pending)
Soft Deletion
- MUST — Bitemporal traversal queries MUST surface deletion via the deletedAt field on the projected Resource. (proof citation:
rfc0036_bitemporal_surfaces_deletion; verification pending) - MUST_NOT — New Statements MUST NOT be created with a soft-deleted subjectId or objectId; rejected with M36050. (proof citation:
rfc0036_no_statement_with_soft_deleted_endpoint; verification pending) - MUST — Reads MUST filter out soft-deleted rows by default but MUST support an explicit includeSoftDeleted: true option. (proof citation:
rfc0036_soft_delete_filter_with_override; verification pending)
The data Blob
- MUST — Inbound JSON null in data MUST be coerced or rejected at the API boundary. (proof citation:
rfc0036_inbound_json_null_coerced_or_rejected; verification pending) - MUST — Persisted data MUST encode bigint values as decimal strings. (proof citation:
rfc0036_bigint_persisted_as_decimal; verification pending) - MUST_NOT — The backend MUST NOT accept a Resource or Statement whose data contains a literal null-valued field; rejected with M36040. (proof citation:
rfc0036_no_null_valued_data_field; verification pending) - RECOMMENDED — Use of the versioned data wrapper is RECOMMENDED for Resource types whose contract is expected to evolve.
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0006 |
| Depends on | RFC-0007 |
| Extended by | RFC-0037 |
| Extended by | RFC-0038 |
| Extended by | RFC-0039 |
| Extended by | RFC-0042 |
| Extended by | RFC-0049 |
| Extended by | RFC-0050 |
| Extended by | RFC-0051 |
| Extended by | RFC-0052 |
| Extended by | RFC-0053 |