gnomonlearn
Docs/Graph/RFC-0036

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.graph platform module declares these (RFC-0052 §3.4). Application modules MUST NOT declare entity-types named Resource or Statement, MUST NOT write to graph.resource or graph.statement directly, 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.statement is reserved to db.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 externalId is the natural key for upsert semantics (RFC-0039 templates and RFC-0041 install engine both rely on this).
  • An externalId MUST 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:

  1. kind MUST be present and non-empty.
  2. data MUST be a JSON-serializable object. The backend MUST NOT silently drop unknown keys.
  3. The shape of data is constrained by the resource type registered for kind (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:

  1. Exactly one of predicateId and predicate MUST be supplied at write time. The backend resolves the missing field.
  2. subjectId and objectId MUST refer to existing, non-deleted Resources at insert time. Historical Statements may continue to reference Resources that are soft-deleted later (§9.2).
  3. validFrom and validTo form a half-open interval [validFrom, validTo) when both are non-null. validFrom > validTo MUST be rejected with M36010.
  4. Multiple statements between the same (subjectId, predicateId, objectId) MAY exist if their validFrom intervals are disjoint. Overlapping intervals on the same triple MUST be rejected with M36011.
  5. 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:

  1. path MUST be a valid ltree path (§3.2).
  2. path MUST be globally unique. Inserting a duplicate path MUST be rejected with M36020.
  3. Predicates MUST NOT be deleted while any Statement references them. Cascade behavior is defined by RFC-0041 install/uninstall.
  4. sameAs is an informational alignment to an external ontology and does not affect runtime evaluation. RFC-0042 §sameAs describes its role in policy.

5. Permission Bits

Permission level is a hierarchical bitmask stored as SMALLINT:

Name (text)ConstantValueBitsIncludes
(none)None00b0000—
readRead10b0001Read
writeWrite30b0011Read, Write
adminAdmin70b0111Read, Write, Admin
ownerGrant150b1111Read, 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:

  1. 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.
  2. The cache MUST be invalidated whenever a policy or relevant Statement is mutated. The invalidation algorithm is specified in RFC-0042.
  3. derivedFrom is 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.

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 pairAxisQuestion answered
createdAt / updatedAt / deletedAtSystem timeWhen did the system learn about this fact?
validFrom / validToValid timeWhen 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 = null means “from the beginning of time” (or “unbounded past”).
  • validTo = null means “still true” (or “unbounded future”).
  • deletedAt = null means 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 subjectId or objectId. Insert MUST be rejected with M36050.
  • Bitemporal traversal queries (RFC-0038) MUST surface the deletion to the caller via the deletedAt field 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.

  1. Every graph entity has a stable, monotonic, backend-allocated bigint id (§3.1).
  2. The pair (kind, externalId) is unique within Resources (§3.3); path is unique within Predicates (§4.3).
  3. Predicates MUST NOT be deleted while referenced (§4.3).
  4. Statement predicateId and predicate MUST be consistent (§3.4); exactly one is required at write time (§4.2 inv 1).
  5. Statement [validFrom, validTo) is a half-open interval; validFrom > validTo is rejected (§4.2 inv 3).
  6. Permission bits are drawn from {0, 1, 3, 7, 15} (§5).
  7. data is a JSON object; literal null field values are rejected (§7.2).
  8. New Statements cannot reference soft-deleted Resources (§9.2).
  9. 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 typeThis 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/