RFC-0036 · Graph Data Model
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 →
Alignment Note (2026-04-30)
Resource and Statement are platform intrinsics, not user-declarable entity types. Per Architecture A (ratified in docs/spikes/findings-postgres-gnomon-bridge.md (see spec source)) and the Q2 plan’s KP19/KP10 (locked):
- Resource and Statement are the universal carrier of the graph (the “gnomon” — see kernel-primitives.md). The shapes documented in §4.1 and §4.2 are the persistent form of object-gnomons and edge-gnomons respectively. There are exactly two physical tables; conceptually they are one primitive.
- Only the
db.graphplatform module declares these (RFC-0052 §3.4). Application modules MUST NOT declare entity-types named Resource or Statement, MUST NOT write tograph.resourceorgraph.statementdirectly, and MUST NOT redefine the schema. - User code interacts with these only through templates, projections, queries, and mutations. Templates (RFC-0039) write; projections (RFC-0049) read; queries and mutations (RFC-0049 §11–§12) are the application-facing surface. Direct CRUD on
graph.resource/graph.statementis reserved todb.graph’s own intrinsic procedures (RFC-0050 §3, RFC-0050 §7). - Where this RFC writes “entity Resource { … }” or “entity Statement { … }” in §4 below, read it as “the platform-intrinsic shape of the object-gnomon / edge-gnomon as installed by
db.graph.” A future revision will rewrite §4 in object-gnomon / edge-gnomon language; this alignment note is the current authoritative interpretation.
The vocabulary in this RFC remains correct; what changes is who declares it and who writes it. The shapes are normative for the db.graph module and for any conforming backend (RFC-0037, RFC-0051) — they are not authoring patterns for application code.
1. Purpose
This RFC defines the canonical noun vocabulary of the Gnomon graph layer: the data shapes that every other graph RFC references. Without these, every subsequent RFC has to redefine half the vocabulary.
The graph data model is what the runtime actually persists. RFC-0007 describes the abstract gnomon semantics (five dimensions, three logical layers); this RFC describes the concrete entity shapes that are stored, queried, and mutated by the backend services in RFC-0037.
This RFC is a faithful codification of the data model already in use in the legacy graph-model and graph-backend-model packages. It is normative — every Gnomon-conformant graph backend MUST implement these shapes exactly.
Per the alignment note above: these shapes are platform intrinsics declared by db.graph (RFC-0052), accessed by user code only through the template/projection/query/mutation surface (RFC-0049, RFC-0050).
2. Defined terms
The complete glossary (Graph entity, ID, Kind, External ID, Predicate, Statement, Bitemporal edge, Workspace, Permission bits, Permission cache, Soft delete) is rendered in reference catalog § Definitions. Authors editing this document should add or refine terms in the structured Lean module at lean/Gnomon/Spec/Graph/Rfc0036.lean.
3. Identity Model
3.1 IDs
Every graph entity has an id of type bigint. IDs are:
- Backend-allocated (never caller-supplied).
- Monotonically increasing within a single backend instance.
- Globally unique across the entity types (a Resource and a Statement MUST NOT share an id).
- Stable for the lifetime of the entity, including across soft delete.
Implementations MAY assign IDs from per-module ranges (the legacy install engine allocates ID ranges to modules at install time per RFC-0041), but the IDs themselves remain a single global namespace.
3.2 Kinds and ltree namespaces
Resource and Workspace kind fields are conventionally ltree paths. The grammar is:
ltree-path ::= ltree-label { "." ltree-label }
ltree-label ::= [A-Za-z_][A-Za-z0-9_]*
The ltree convention (drawn from PostgreSQL) supports prefix matching (<@) and is used by the predicate-policy matchMode: subtree (RFC-0042).
Backends MUST treat the kind field as opaque text but SHOULD index it for prefix and equality lookups.
3.3 External IDs
Resources MAY carry an externalId of type string. When present:
- The pair
(kind, externalId)MUST be unique within the backend. - The
externalIdis the natural key for upsert semantics (RFC-0039 templates and RFC-0041 install engine both rely on this). - An
externalIdMUST NOT be reassigned to a different Resource after deletion of the original.
When externalId is absent, the only stable handle to the Resource is its id.
3.4 Predicate identity
Predicates are first-class graph entities with their own id. They are referenced from Statements two ways:
predicateId: bigint— the foreign-key reference (canonical, indexed).predicate: string— the denormalized ltree path (for human readability and for query filters).
Both fields MUST be present on a persisted Statement; the backend MUST keep them consistent. Insert paths SHOULD accept either form and resolve the missing field.
4. Core Entity Types
4.1 Resource
A Resource is a typed node in the graph. Every persistable thing other than relations and policy is a Resource.
Resource {
objectType: "resource"
id: bigint
kind: string // ltree path; classifies the resource
externalId: string | null
data: Map<String, Any> // typed by `kind`
creatorId: bigint | null
createdAt: Instant
updatedAt: Instant
deletedAt: Instant | null // soft delete
}
ResourceInput is the write-side shape:
ResourceInput {
objectType: "resource_input"
id: bigint | undefined // optional; usually backend-allocated
kind: string
externalId: string | null
data: Map<String, Any>
creatorId: bigint | null
}
Invariants:
kindMUST be present and non-empty.dataMUST be a JSON-serializable object. The backend MUST NOT silently drop unknown keys.- The shape of
datais constrained by the resource type registered forkind(RFC-0040 §resource_type). Validation against the registered shape is the responsibility of the client (RFC-0038), not the backend.
4.2 Statement
A Statement is a typed, bitemporal edge between two Resources.
Statement {
objectType: "statement"
id: bigint
subjectId: bigint // FK -> Resource.id
objectId: bigint // FK -> Resource.id
predicateId: bigint // FK -> Predicate.id
predicate: string // denormalized ltree path
data: Map<String, Any> // edge attributes
validFrom: Instant | null // edge bitemporality (when relation became true)
validTo: Instant | null // (when relation ceased to be true)
creatorId: bigint | null
createdAt: Instant
updatedAt: Instant
deletedAt: Instant | null
}
StatementInput is the write-side shape:
StatementInput {
objectType: "statement_input"
subjectId: bigint
objectId: bigint
predicateId: bigint | undefined // either predicateId OR predicate MUST be supplied
predicate: string | undefined
data: Map<String, Any>
validFrom: Instant | null
validTo: Instant | null
creatorId: bigint | null
}
Invariants:
- Exactly one of
predicateIdandpredicateMUST be supplied at write time. The backend resolves the missing field. subjectIdandobjectIdMUST refer to existing, non-deleted Resources at insert time. Historical Statements may continue to reference Resources that are soft-deleted later (§9.2).validFromandvalidToform a half-open interval[validFrom, validTo)when both are non-null.validFrom > validToMUST be rejected withM36010.- Multiple statements between the same
(subjectId, predicateId, objectId)MAY exist if theirvalidFromintervals are disjoint. Overlapping intervals on the same triple MUST be rejected withM36011. - Statements MUST NOT be silently deduplicated by the backend; the client controls upsert semantics (RFC-0037
statement.upsert).
4.3 Predicate
A Predicate is the relation type referenced by Statements. Predicates are themselves graph entities, persisted in the backend.
Predicate {
objectType: "predicate"
id: bigint
path: string // ltree path; globally unique
sameAs: string | null // optional CURIE alignment (e.g. "schema:memberOf")
description: string | null
createdAt: Instant
updatedAt: Instant
}
Invariants:
pathMUST be a valid ltree path (§3.2).pathMUST be globally unique. Inserting a duplicate path MUST be rejected withM36020.- Predicates MUST NOT be deleted while any Statement references them. Cascade behavior is defined by RFC-0041 install/uninstall.
sameAsis an informational alignment to an external ontology and does not affect runtime evaluation. RFC-0042 §sameAsdescribes its role in policy.
5. Permission Bits
Permission level is a hierarchical bitmask stored as SMALLINT:
| Name (text) | Constant | Value | Bits | Includes |
|---|---|---|---|---|
| (none) | None | 0 | 0b0000 | — |
read | Read | 1 | 0b0001 | Read |
write | Write | 3 | 0b0011 | Read, Write |
admin | Admin | 7 | 0b0111 | Read, Write, Admin |
owner | Grant | 15 | 0b1111 | Read, Write, Admin, Grant |
The text name owner maps to the constant Grant (the highest level — the bit that authorizes granting permissions to other subjects). This naming is preserved for compatibility with the legacy predicate_policy.permission_bits column.
Permission checks MUST use bitwise comparison: current >= required is true when every bit set in required is also set in current. Equivalently:
hasPermission(current, required) = (current & required) === required
The bitmask is total-ordered for the four named levels but can in principle represent any subset of the four bits. The runtime MUST treat values outside {0, 1, 3, 7, 15} as a defect (M36030); they MUST NOT be silently normalized.
6. Auxiliary Entity Types
6.1 Workspace
A Workspace is a top-level Resource that defines a tenant or environment scope. All Resources and Statements within an Gnomon runtime SHOULD be reachable from at least one Workspace.
Workspace {
objectType: "workspace"
id: bigint
kind: string
externalId: string | null
data: Map<String, Any>
permissionBits: number | null // workspace-level default permission
creatorId: bigint | null
createdAt: Instant
updatedAt: Instant
deletedAt: Instant | null
}
The permissionBits field expresses a default permission level granted to all members of the workspace. It is not authoritative — predicate policies (RFC-0042) and per-resource policies (§6.3) override it.
RFC-0045 defines the deployment tenant-mode setting and RFC-0051 defines PostgreSQL RLS binding. The complete tenancy model remains deferred to a future RFC.
6.2 PermissionCache
A PermissionCache row materializes the effective permission of a (subject, resource) pair after policy evaluation. It is a backend optimization, not a source of truth — the backend MAY evict and recompute at any time.
PermissionCache {
objectType: "permission_cache"
id: bigint
subjectId: bigint
subjectKind: string
resourceId: bigint
resourceKind: string
permissionBits: number
derivedFrom: Map<String, Any> | null // explanation: which policies contributed
computedAt: Instant
expiresAt: Instant | null
isValid: boolean
invalidatedAt: Instant | null
invalidatedReason: string | null
}
Invariants:
- The cache is non-authoritative. Reads MAY consult the cache, but writes that would depend on a permission decision MUST re-evaluate or hold a write-side lock.
- The cache MUST be invalidated whenever a policy or relevant Statement is mutated. The invalidation algorithm is specified in RFC-0042.
derivedFromis informational and MAY be populated for audit (RFC-0047).
6.3 ResourcePolicy and StatementPolicy
Per-resource and per-statement-type permission policies. Distinct from predicate policies (RFC-0042) — these grant permissions on Resources or Statements directly, not through a predicate relation.
ResourcePolicy {
objectType: "resource_policy"
id: bigint
resourceType: string | null // null = applies to all kinds
permissions: number // permission bits granted
description: string | null
isActive: boolean
priority: number
createdAt: Instant
updatedAt: Instant
createdBy: string | null
}
StatementPolicy {
objectType: "statement_policy"
id: bigint
statementType: string // the predicate this policy applies to
resourceType: string | null
permissions: number
description: string | null
isActive: boolean
priority: number
createdAt: Instant
updatedAt: Instant
createdBy: string | null
}
These types exist for completeness — most authorization should use predicate policies (RFC-0042). Implementations MAY treat resource and statement policies as a degenerate case of predicate policies (with predicate = null), but the data shape is preserved here for direct migration of legacy schema.
6.4 ExternalLink
An ExternalLink ties a graph entity to a row in an external (non-graph) database table. Used by the legacy sync/reflection layer.
ExternalLink {
objectType: "external_link"
id: bigint
tableOid: number
tableSchema: string
tableName: string
predicate: string
primaryKeyColumns: List<String>
syncMode: string
createdAt: Instant
updatedAt: Instant
enabled: boolean
}
The full sync semantics are out of scope for this RFC; ExternalLink is documented here only because it is part of the persisted graph data model. A future RFC will specify external-table sync.
7. The data Blob
Every Resource, Statement, and Workspace carries a data field of type Map<String, Any> — the JSON object payload. The shape of data is determined by the entity’s kind (Resource, Workspace) or predicate (Statement) and is registered by a resource_type declaration in a module manifest (RFC-0040).
7.1 Versioned data wrapper
Implementations MAY wrap data in a versioned envelope to support schema evolution:
VersionedData<V, TData, TMeta> {
schemaVersion: V // integer
metadata: TMeta | null
data: TData
}
When this wrapper is used, migrations (RFC-0016) operate on the data field; schemaVersion is bumped by the migration intrinsic.
Use of the wrapper is optional but RECOMMENDED for any Resource type whose contract is expected to evolve.
7.2 Null prohibition
Per RFC-0006 §4.A invariant 7, null is not a valid value within data. Inbound JSON null MUST be coerced or rejected at the API boundary (RFC-0034 §5.2). The backend MUST NOT accept a Resource or Statement whose data contains a literal null-valued field; such inserts MUST be rejected with M36040.
Optional fields that are absent are simply omitted from the data map.
7.3 BigInt encoding
Because JSON cannot represent bigint, persisted data MUST encode bigint values as decimal strings. The transport layer (RFC-0034 §5) is responsible for round-tripping the encoding. Backends MAY accept either form on write; on read, they MUST emit the form documented by their query API.
8. Bitemporality
8.1 Resource bitemporality (RFC-0007)
Resource-level bitemporality (createdAt / updatedAt / deletedAt) is defined in RFC-0007. This RFC does not redefine those semantics; the columns appear in the Resource shape (§4.1) for completeness only.
8.2 Statement bitemporality (this RFC)
Statements add a second bitemporal axis: validFrom / validTo. These columns capture when the asserted relation was true in the world, distinct from when it was recorded (the createdAt / updatedAt axis from RFC-0007).
| Column pair | Axis | Question answered |
|---|---|---|
createdAt / updatedAt / deletedAt | System time | When did the system learn about this fact? |
validFrom / validTo | Valid time | When was the asserted relation actually true? |
A query at system-time T_sys and valid-time T_val returns a Statement when:
T_sys ∈ [createdAt, deletedAt) AND T_val ∈ [validFrom, validTo)
Either bound may be null:
validFrom = nullmeans “from the beginning of time” (or “unbounded past”).validTo = nullmeans “still true” (or “unbounded future”).deletedAt = nullmeans the system still believes the fact (no soft delete).
8.3 Combined queries
Implementations MUST support asOf(t) queries that fix system time, validAt(t) queries that fix valid time, and the combined asOf(t_sys).validAt(t_val) form. The query API surface is defined in RFC-0038.
9. Soft Deletion
9.1 Mechanics
All entity types EXCEPT Predicate carry a deletedAt column (Predicate has no deletedAt because Predicates MUST NOT be deleted while any Statement references them — see §4.3 invariant 3).
Setting deletedAt = <instant> logically deletes the entity. The row remains in the backend; reads MUST filter out soft-deleted rows by default but MUST be able to include them via an explicit includeSoftDeleted: true option.
9.2 Statements referencing soft-deleted Resources
When a Resource is soft-deleted, Statements that reference it (subjectId or objectId) are NOT automatically soft-deleted. They remain queryable for audit. However:
- New Statements MUST NOT be created with a soft-deleted
subjectIdorobjectId. Insert MUST be rejected withM36050. - Bitemporal traversal queries (RFC-0038) MUST surface the deletion to the caller via the
deletedAtfield on the projected Resource.
9.3 Hard deletion
Hard deletion is supported only by the install/uninstall path (RFC-0041) and only as part of a transactional uninstall. There is no online hard-delete API.
10. Invariants — narrative summary
A reader-friendly summary of the load-bearing invariants from §3–§9. The canonical machine-readable list lives in reference catalog § Invariants; when this prose summary and the structured catalog differ, reconcile their source facts before treating either as normative.
- Every graph entity has a stable, monotonic, backend-allocated
bigintid (§3.1). - The pair
(kind, externalId)is unique within Resources (§3.3);pathis unique within Predicates (§4.3). - Predicates MUST NOT be deleted while referenced (§4.3).
- Statement
predicateIdandpredicateMUST be consistent (§3.4); exactly one is required at write time (§4.2 inv 1). - Statement
[validFrom, validTo)is a half-open interval;validFrom > validTois rejected (§4.2 inv 3). - Permission bits are drawn from
{0, 1, 3, 7, 15}(§5). datais a JSON object; literalnullfield values are rejected (§7.2).- New Statements cannot reference soft-deleted Resources (§9.2).
- The PermissionCache is non-authoritative; writes MUST re-evaluate (§6.2 inv 1).
11. Compatibility and Migration
11.1 From legacy graph-model
This RFC is a faithful codification of the legacy shapes in:
/Volumes/Workspace/savvi-studio-full/packages/graph-model/mapped-objects.ts— Resource, Statement, Workspace, PermissionCache, ResourcePolicy, StatementPolicy, ExternalLink/Volumes/Workspace/savvi-studio-full/packages/graph-model/permissions.ts— PermissionLevel bitmask, PermissionLevelName, PERMISSION_BITS map
The mapping is direct:
| Legacy type | This RFC |
|---|---|
Resource | §4.1 |
ResourceInput | §4.1 |
Statement | §4.2 |
StatementInput | §4.2 |
Workspace | §6.1 |
WorkspaceInput | (omitted; same shape as Workspace minus computed fields) |
PermissionCache | §6.2 |
ResourcePolicy | §6.3 |
StatementPolicy | §6.3 |
ExternalLink | §6.4 |
PermissionLevel enum | §5 |
PermissionLevelName | §5 |
PERMISSION_BITS | §5 |
11.2 From legacy YAML manifests
Module manifests in modules/src/* declare resource, statement, predicate, and predicate_policy objects. Those declarations are install-time inputs that produce graph entities of the shapes defined here. The mapping from YAML to this data model is the responsibility of RFC-0040 (Module Manifest) and RFC-0041 (Install Engine).
11.3 Snake_case vs camelCase
The legacy backend stores columns as snake_case (e.g., external_id, valid_from) and exposes them as camelCase (e.g., externalId, validFrom) at the client API. This RFC uses camelCase for all field names. Backend implementations MAY use any internal column naming; the wire surface defined here is camelCase.
12. Diagnostics
The diagnostic catalog (codes M36010, M36011, M36020, M36021, M36030, M36040, M36050, M36060, M36061, M36070, M36080) is authored in the structured Lean module and rendered in reference catalog § Diagnostics. Inline mentions in the prose above (e.g., “rejected with M36010”) can be checked against the catalog.
13. Linked References
The cross-RFC dependency graph (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) is rendered in reference catalog § Linked References.
Source-tree references
Out-of-KG pointers to legacy code that this RFC codifies:
/Volumes/Workspace/savvi-studio-full/packages/graph-model/mapped-objects.ts/Volumes/Workspace/savvi-studio-full/packages/graph-model/permissions.ts/Volumes/Workspace/savvi-studio-full/packages/graph-backend-model/model/