RFC-0007 · Gnomon Primitive and Storage 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 →
Status: Draft Owners: Semantic Core, Runtime
1. Scope
Defines the gnomon as the universal semantic primitive: a typed, identity-bearing, provenance-carrying unit of meaning. Covers (a) the conceptual model for what an gnomon is, (b) the application-layer three-layer logical model, (c) the physical storage strategy over PostgreSQL, and (d) the gnomon query and derivation APIs.
This RFC is the data model contract for the runtime. The semantic type model (RFC-0006) governs what can be declared. This RFC governs how declared types are stored, traversed, and queried at runtime.
The gnomon primitive is an application-layer abstraction compiled to standard PostgreSQL. A Postgres-native type extension (pg_gnomon) is a longer-term possibility and is tracked as an open question; it does not affect the normative surface defined here.
2. Goals
- Provide a single modeling primitive that unifies entities, relationships, documents, embeddings, and derived facts
- Eliminate manual relational plumbing for applications that reason semantically
- Make AI-generated and AI-consumed data first-class in the storage layer
- Support graph-style traversal without requiring a graph database
- Define clear physical storage patterns that remain performant on PostgreSQL
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.
3. Invariants
- Every gnomon instance MUST have a stable internal UUID.
- Every gnomon instance MUST carry a
kindreferencing a declared semantic type kind. - Every gnomon instance MUST carry an
epistemic_statusfrom the allowed set. - Relations MUST be stored as edge-gnomons with explicit
subject,predicate, andobject. - Derived gnomons MUST carry lineage linking them to the source gnomons and derivation rule used.
- Physical projection tables MUST be generated from the logical model; they MUST NOT be hand-authored.
4. Five Dimensions of an Gnomon
Every gnomon instance carries five inseparable dimensions:
4.1 Identity
A stable UUID assigned at creation. Two gnomons that represent the same real-world entity MAY share a canonical_identity key, but they MUST have distinct UUIDs until explicitly merged. Identity merge is an explicit lifecycle operation, not implicit.
4.2 Semantic Kind
The declared type of the gnomon’s content, drawn from pg_gnomon_kind (or its application-layer equivalent). Not merely a string tag — the kind determines available operators, indexing strategies, and validation rules. Examples: Person, PolicyClause, ClaimEvent, Hypothesis.
4.3 Representation Set
A single gnomon MAY carry multiple physical representations of the same semantic content:
- canonical structured payload (JSONB)
- text rendering
- embedding vector
- sparse feature map
- generated summary
Representations are derived from the canonical payload. The canonical payload is authoritative; other representations are projections.
4.4 Epistemic Status
The confidence and provenance posture of the value:
asserted— explicitly provided by a human or trusted systemobserved— recorded from a raw event or sensorinferred— derived from rules or logicestimated— produced by a statistical or ML modelpredicted— forecast for a future statedisputed— contradicted by another sourcesuperseded— replaced by a newer gnomon
Queries and policies MAY predicate on the gnomon’s epistemic_status. A gnomon with epistemic_status: inferred MUST NOT be treated as ground truth without explicit verification. This gnomon-level status describes origin and confidence posture; it is distinct from a Claim<T> field’s status, which follows the RFC-0006 ClaimStatus flow.
4.5 Lineage
Every gnomon MAY carry a lineage reference encoding:
- source gnomon IDs
- derivation rule or model ID/version
- confidence
- timestamp range
- supersession chain
Lineage is required for all derived gnomons. Lineage enables provenance-preserving queries and audit reconstruction.
5. Three-Layer Logical Model
The application-layer logical model has three layers.
Layer 1: Gnomon Kinds
Semantic types declared in the authoring layer. These are what application code and AI workflows address. Examples: Person, Organization, PolicyClause, ClaimEvent, Hypothesis, DocumentChunk.
Layer 2: Gnomon Relations
First-class semantic edges between gnomon instances. Relations are not mere join tables; they are typed, named, and carry qualifiers and confidence. Examples: belongs_to, supports, contradicts, derived_from, covers, occurred_at.
Relations that are themselves domain-meaningful (e.g., an enrollment event) SHOULD be modeled as edge-gnomons with their own identity, not as bare foreign key associations.
Layer 3: Gnomon Projections
Optimized views of the logical model for specific access patterns:
- relational row projection (typed columns per kind)
- document projection (JSONB payload)
- embedding projection (vector column)
- search projection (tsvector or external index)
- timeline projection (bitemporal or event-ordered view)
- API projection (serialized DTO shape)
A single logical gnomon definition can produce multiple physical projections. Authors declare projections at the model layer; the runtime generates the DDL.
6. Physical Storage Strategy
The physical implementation uses a hybrid: a universal base table for common metadata, an edge table for relations, typed projection tables for high-value kinds, specialized support tables, and a dedicated claim evidence table for evidence-typed fields.
6.0 Claim Field Storage
Claim<T> fields (RFC-0006 §4.5) require special storage treatment because they carry evidence metadata alongside the field value. Three storage strategies are available; the compiler selects the appropriate strategy per field based on the field’s declaration.
Strategy A — Inline JSONB (default)
The claim is stored as a structured JSONB object within the base table’s payload column:
{
"diagnosisCode": {
"_claim": true,
"value": "Z87.39",
"status": "pending",
"confidence": 0.87,
"source": "model:clinical-extractor-v2",
"asserted_by": "agent:document-extraction",
"asserted_at": "2026-04-28T10:00:00Z",
"evidence_links": ["gnomon:doc-chunk-uuid-1"]
}
}
The _claim: true sentinel MUST be present so the kernel can distinguish claim fields from plain fields without schema lookup at read time. This strategy is used when the field has low query frequency and no declared confidence-threshold policy.
The example’s pending status is a ClaimStatus state; an enclosing AI-derived gnomon may separately have epistemic_status: inferred.
Strategy B — Dedicated evidence columns in projection table (for query-hot fields)
When a claim field is declared with policies.min_confidence_to_use or is referenced in queries, the compiler MUST generate explicit columns in the projection table:
-- In the kind's projection table
diagnosis_code text,
diagnosis_code_status text, -- ClaimStatus flow state
diagnosis_code_conf numeric, -- confidence score
diagnosis_code_source text, -- model/actor ID
diagnosis_code_agent text, -- asserting agent
diagnosis_code_at timestamptz,
diagnosis_code_evid uuid[] -- evidence_links
The projection table MUST have a generated index on <field>_conf and <field>_status when confidence-threshold policies are declared.
Strategy C — Evidence side-table (for high-cardinality evidence links)
When a claim field declares many evidence links or requires full audit history, the compiler generates an entry in gnomon_claim_evidence:
gnomon_claim_evidence (
id uuid primary key default gen_random_uuid(),
gnomon_id uuid not null references gnomon(id),
field_path text not null, -- e.g. 'diagnosisCode'
value_json jsonb not null,
status text not null,
confidence numeric,
source text,
asserted_by text,
asserted_at timestamptz,
superseded_by uuid references gnomon_claim_evidence(id),
system_time tstzrange
)
This table supports full claim history per field, including supersession chains. Strategy C is automatically selected when the claim’s allowed_status includes disputed or superseded (dispute history is required, but no threshold-query projection columns are needed). When policies.requires_human_review_below is declared, both B and C are selected: Strategy B generates projection columns for confidence-threshold queries, and Strategy C maintains the full audit history required for human review workflows.
Strategy selection rules (normative)
| Condition | Strategy |
|---|---|
| No confidence policy, low query frequency | A (inline JSONB) |
min_confidence_to_use declared | B (projection columns) |
requires_human_review_below declared | B + C |
allowed_status includes disputed or superseded | C |
Field appears in a declared query’s where clause | B |
The compiler MUST emit the selected strategy in the storage manifest (RFC-0002 §7) so the install pipeline applies the correct DDL. A field MUST NOT use different strategies across module versions without a migration operation.
Kernel enforcement of claim constraints
The kernel (RFC-0010 §5.2) MUST enforce the following at write time for every claim field write:
required_evidencefields declared in the claim’s authoring declaration MUST all be present; missing fields produce error M07030.allowed_statusconstraints MUST be checked; out-of-range status produces error M07031.min_confidence_to_useMUST be checked before the claim value is surfaced in query results or action preconditions; values below threshold MUST be filtered or gated as declared.- An AI agent writing a claim field MUST have the writing action listed in its
permissionsblock (RFC-0009 §4); violations produce error M09811 (RFC-0009 allocation).
6.0a Scale and Sharding Strategy
The universal base table is designed for single-tenant deployments up to approximately 50M rows. Beyond that threshold, the recommended sharding strategy is namespace-level PostgreSQL table partitioning by kind prefix:
-- Partition the base table by module namespace prefix
CREATE TABLE gnomon (...)
PARTITION BY LIST (split_part(kind, '.', 1));
-- One partition per top-level namespace (e.g., 'org', 'gnomon', 'hr')
CREATE TABLE gnomon_org PARTITION OF gnomon
FOR VALUES IN ('org');
Rules:
- Partitioning is declared in the module’s storage manifest (RFC-0002 §7); the install pipeline generates the DDL.
- The query API MUST be partition-transparent — callers MUST NOT need to know which partition holds a given gnomon.
- Cross-partition joins (e.g., traversing a relation from
org.plans.Plantohr.Person) are permitted but MUST be declared as cross-module relations in the authoring layer; the compiler generates the appropriate join strategy. - Sharding across physical hosts (not just Postgres partitions) is deferred to a future RFC. The normative storage model here assumes a single Postgres instance or a horizontally read-scaled replica set. Open question on multi-host write sharding is tracked in QA.md.
6.1 Universal Base Table
gnomon (
id uuid primary key default gen_random_uuid(),
kind text not null,
identity jsonb, -- canonical identity keys
payload jsonb, -- canonical structured payload
status text not null, -- epistemic_status
confidence numeric,
valid_time tstzrange,
system_time tstzrange,
created_at timestamptz not null default now(),
updated_at timestamptz
)
6.2 Edge Table
gnomon_edge (
id uuid primary key default gen_random_uuid(),
subject_id uuid not null references gnomon(id),
predicate text not null,
object_id uuid references gnomon(id),
object_literal jsonb,
qualifiers jsonb,
provenance_id uuid references gnomon(id),
confidence numeric,
system_time tstzrange
)
6.3 Projection Tables
Generated from model declarations. Example:
person_projection (
id uuid primary key,
name text,
email text,
employer_id uuid
)
Projection tables are regenerated or migrated by the install pipeline (RFC-0005). Authors MUST NOT write to projection tables directly; all writes go through the gnomon API.
6.4 Support Tables
gnomon_embedding (gnomon_id uuid, model_id text, vector float4[])
gnomon_lineage (gnomon_id uuid, source_id uuid, rule_id text, model_id text,
confidence numeric, created_at timestamptz)
gnomon_observation (gnomon_id uuid, field text, raw_value jsonb, source text,
observed_at timestamptz)
Embedding projection placement: By default, embedding vectors live in gnomon_embedding (the support table). This is the correct default for most use cases because embeddings are large, model-versioned, and rarely needed alongside structured fields in the same query.
A module MAY promote embeddings to the projection table by declaring projection { embedding: true } on the derive block:
derive ClauseEmbedding {
input: PolicyClause.text
produces: Embedding
method: embedding_model
projection: { embedding: true } // inline in projection table
}
When projection: { embedding: true } is declared, the compiler generates an embedding vector(1536) column (or the declared dimension) in the kind’s projection table and populates it alongside gnomon_embedding. This is appropriate only when the embedding is always needed in the same query as the structured fields (e.g., ANN search with field filters). The dual write (support table + projection column) is the compiler’s responsibility; authors MUST NOT manage both paths manually.
7. Gnomon Query API
The semantic query API allows path-based traversal without exposing SQL to application code.
7.0 Bitemporal Read Semantics
Every gnomon carries two time dimensions:
| Dimension | Column | Meaning | Visibility |
|---|---|---|---|
| valid_time | valid_time tstzrange | The time period during which the value is considered true in the domain | User-visible |
| system_time | system_time tstzrange | The time period during which this row existed in the database (append-only) | Internal bookkeeping |
User-visible valid_time: Authors set valid_time when writing a value (e.g., “this plan rate is effective from 2026-01-01 to 2026-12-31”). Queries default to valid_time @> now() — returning only currently-valid records. This default is always explicit; the query API MUST NOT silently filter on any other dimension.
asOf queries: The query API exposes asOf(date) to read the state of the object graph at a past or future valid_time point:
// What plans were valid on 2025-06-01?
// Note: `Plan` and `benefitType` are illustrative example names only;
// they are not declared in the Gnomon standard library.
gnomon.find("Plan", { where: { benefitType: "medical_plan" } }).asOf("2025-06-01");
// What did we know about this person on 2026-01-15?
gnomon.resolve("Person", { id: personId }).asOf("2026-01-15");
asOf filters to rows where valid_time @> asOf_date. It does NOT filter on system_time — for that, use asRecordedAt (audit reads, not business reads).
asRecordedAt queries (audit): Read what the database contained at a past transaction time:
gnomon.find("Bundles", { where: { household: householdId } }).asRecordedAt("2026-03-01T12:00:00Z");
Invariants:
system_timerecords are append-only. No UPDATE or DELETE may change a committedsystem_timerow.valid_timemay be set by authors but MUST NOT be set in the past forClaim<T>fields without an explicitbackdated: trueflag and a policy-authorized actor.asOfandasRecordedAtqueries MUST NOT be used in preconditions or effects of action declarations — they are read-only audit primitives.
7.1 Find
// Note: `Plan` and `benefitType` are illustrative example names only;
// they are not declared in the Gnomon standard library.
gnomon.find("Plan", {
where: {
benefitType: "medical_plan",
household: { id: householdId }
},
select: {
id: true,
name: true,
monthlyPremium: true,
deductible: true
},
orderBy: { monthlyPremium: "asc" },
limit: 20,
offset: 0
})
// Defaults to valid_time @> now(). Override with .asOf(date).
Predicate operators: ==, !=, <, <=, >, >=, in, contains, startsWith. Nested predicates follow dot-path field access matching RFC-0008 §8.22 expression syntax. The query predicate language is a subset of the RFC-0018 ExprContext expression language; implementations MUST use the same parser.
Query predicates in where clauses use the same expression language as RFC-0018’s ExprContext constraint expressions (RFC-0018 §6.2). The compiler evaluates where predicates in ParseContext InQueryBody. All path traversal expressions, comparison operators, logical connectives, and field access patterns defined in RFC-0021 §3 are valid in query predicates. Arithmetic is permitted in predicates but the result type MUST be boolean. The compiler MUST emit M07622 if a predicate expression cannot be statically typed.
Pagination: limit and offset are both optional integers. limit defaults to 100; implementations MUST enforce a configurable maximum (default 1000).
Ordering: orderBy is a map of field path → "asc" | "desc". Multiple fields are ordered left-to-right.
7.2 Resolve
Load a single gnomon by identity or canonical key:
gnomon.resolve("Person", { id: personId });
// Returns null if not found; throws if multiple match.
7.3 Traverse
Follow semantic relations without manual joins:
gnomon.traverse(planId, ["benefits", "benefits.person"]);
// Returns the named relation paths for the root gnomon.
7.4 Aggregate
gnomon.aggregate("Benefit", {
where: { household: { id: householdId } },
groupBy: ["benefitType"],
compute: {
count: { fn: "count" },
totalPremium: { fn: "sum", field: "monthlyPremium" }
}
});
Supported aggregate functions: count, sum, avg, min, max. groupBy field paths follow the same dot-path syntax as where predicates.
7.5 RenderContext
Produce a coherent semantic neighborhood for LLM context injection:
gnomon.renderContext({
root: planId,
include: ["benefits", "benefits.person", "household"]
});
The gnomon layer serializes provenance, confidence, and linked neighbors into a structured context without custom join logic per feature.
7.6 Identity Merge
When two gnomon instances are determined to represent the same real-world entity, an explicit gnomon.merge operation resolves the duplication. Identity merge is NOT implicit deduplication; it is a declared lifecycle operation that MUST be authorized by a policy-permitted actor.
gnomon.merge({
canonical: canonicalId, // the gnomon to keep as authoritative
duplicate: duplicateId, // the gnomon to retire
reason: "manual-dedup" // required: short reason string
})
Merge semantics:
- The
duplicategnomon’sstatusMUST be set tosupersededand a lineage record created pointing fromduplicatetocanonical. - All
gnomon_edgerows referencingduplicateassubject_idorobject_idMUST be updated to referencecanonical. The update MUST be performed atomically with the status change. - A redirect record MUST be written to
gnomon_merge(defined below) so that reads against the retired UUID can resolve to the canonical instance. - The
duplicategnomon’s UUID is retained in storage; it MUST NOT be deleted. Tombstoning viasupersededstatus satisfies audit requirements. gnomon.resolveMUST follow merge redirects transparently. Callers that explicitly read a superseded gnomon by ID MUST receive the canonical gnomon with amergedFrommetadata field.
gnomon_merge table (generated by install pipeline):
gnomon_merge (
duplicate_id uuid not null references gnomon(id),
canonical_id uuid not null references gnomon(id),
merged_at timestamptz not null default now(),
merged_by text not null, -- actor identity
reason text not null,
primary key (duplicate_id)
)
Authorization: The module MUST declare a merge permission on the entity kind; actors without this permission MUST NOT call gnomon.merge for that kind (M07602).
Diagnostics: M07600–M07603 apply to identity merge operations. See §11 for authoritative definitions.
8. Derivation Contract
Derived gnomons MUST be declared at the model layer, not implemented ad hoc. Derivation declarations use .gnm syntax within the source entity or in a dedicated derivations file.
derive ClaimSummary {
input: Claim
produces: DocumentSummary
method: llm
provenance: required
mode: async
maxStaleness: 5m
}
derive ClauseEmbedding {
input: PolicyClause.text
produces: Embedding
method: embedding_model
mode: async
}
Scheduling modes:
| Mode | Behavior | When to use |
|---|---|---|
async (default) | Triggered by source gnomon writes; executed by background worker | Most derivations |
sync | Derived gnomon is produced inline during the source write transaction | Latency-critical derived fields that must be consistent with the write |
mode: sync MUST only be used for lightweight, deterministic derivation methods (not llm or embedding_model). Using mode: sync with non-deterministic methods produces error M07622.
maxStaleness: Declares the maximum acceptable lag between source gnomon update and derived gnomon update. Expressed as a duration (5m, 1h, 24h). If the derived gnomon is not refreshed within this window after a source update, the runtime MUST flag it as stale (M07621) and MUST NOT surface it in query results unless the caller explicitly sets allowStale: true. When absent, no staleness timeout is enforced.
The runtime manages physical derivation scheduling. Derived gnomons MUST carry lineage back to source gnomons and the derivation rule version. Stale derivations (source updated, derived not regenerated) MUST be detectable via system_time comparison.
9. Relation Declarations
Relations MUST be declared once at the model layer; the framework generates typed accessors, SQL joins, preload strategies, and API fields. Relation declarations use .gnm syntax within entity declarations or in a separate relations file.
entity Claim {
fields { ... }
relations {
member {
via: statement predicate has_member
to: Person
cardinality: one
}
denialReason {
via: statement predicate has_denial_reason
to: Statement
cardinality: one
}
}
}
entity Statement {
fields { ... }
relations {
supportedBy {
via: edge predicate supported_by
to: PolicyClause
cardinality: many
}
}
}
Undeclared traversal paths MUST NOT be permitted in the query API. Attempting to traverse an undeclared relation MUST produce a compile-time or runtime diagnostic.
10. Generated Views
The runtime SHOULD generate SQL views or materialized views for common access shapes declared in the model or projection layer. These serve two purposes: high-performance read paths and debuggability (teams can inspect raw relational state).
Generated views are named deterministically from the model (e.g., claim_with_member_view). Authors SHOULD NOT query the base tables directly in application code.
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.
12. Security and Authorization
- All writes to gnomon instances MUST pass through the gnomon API; direct table writes MUST be rejected in production mode.
- Epistemic status MUST be set by the writing actor, not derived post-hoc by a separate process.
- Lineage references MUST be immutable after creation.
- AI-derived gnomons MUST carry status
estimated,inferred, orpredictedunless explicitly adjudicated by an authorized human actor.
13. Compatibility and Migration
- Adding a new kind is a non-breaking change.
- Adding a new relation between existing kinds is a non-breaking change.
- Changing the canonical payload schema of a kind is a breaking change; a migration plan is required.
- Dropping a kind requires confirming no live gnomon instances exist in that kind.