RFC-0007 · 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-0007: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0007.This page is generated from the
lean/Gnomon/Spec/module for RFC-0007. Edit that source and regenerate this catalog.
Title: Gnomon Primitive and Storage Model
Status: draft
Owners: Runtime, Semantic Core
Proof citations in source: 36 / 36. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| Epistemic Status | Confidence/provenance posture of a value: asserted, observed, inferred, estimated, predicted, disputed, or superseded. |
| Gnomon Kinds | Layer 1 — semantic types declared in the authoring layer that application code and AI workflows address. |
| Gnomon Projections | Layer 3 — optimized physical views (relational, document, embedding, search, timeline, API) of the logical model. |
| Gnomon Relations | Layer 2 — first-class typed semantic edges between gnomon instances carrying qualifiers and confidence. |
| Identity | A stable UUID assigned at gnomon creation; merge is an explicit lifecycle operation. |
| Identity Merge | Explicit lifecycle operation that retires a duplicate gnomon in favor of a canonical one, requiring authorization. |
| Lineage | Reference encoding source gnomon IDs, derivation rule/model ID/version, confidence, timestamp range, and supersession chain. |
| Representation Set | Multiple physical representations of the same semantic content, derived from an authoritative canonical payload. |
| Semantic Kind | The declared type of an gnomon’s content drawn from pg_gnomon_kind, determining operators, indexing, and validation. |
| asOf query | Read primitive returning the state of the object graph at a past or future valid_time point. |
| asRecordedAt query | Audit read primitive returning what the database contained at a past transaction (system_time) point. |
| system_time | Internal append-only time range during which a row existed in the database. |
| valid_time | User-visible time range during which an gnomon’s value is considered true in the domain. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M07030 | Error | Claim write missing required evidence field |
M07031 | Error | Claim write uses status value not in allowed_status |
M07032 | Error | Claim storage strategy changed between versions without migration operation |
M07033 | Error | Claim field below min_confidence_to_use surfaced in query result (runtime enforcement gap) |
M07034 | Error | Kernel claim enforcement skipped — claim declaration not found in module registry |
M07600 | Error | Gnomon created without kind declaration |
M07601 | Error | Canonical identity collision detected on merge — conflicting canonical instances |
M07602 | Error | Actor not authorized to merge gnomons of this kind |
M07603 | Error | Merge attempted on gnomon already marked superseded |
M07610 | Error | Traversal path references undeclared relation |
M07611 | Error | Edge created with subject/object kind mismatch against declared relation |
M07620 | Error | Derived gnomon missing lineage reference |
M07621 | Warning | Stale derived gnomon detected — source updated beyond maxStaleness window |
M07622 | Error | mode:sync declared on non-deterministic derivation method (llm, embedding_model) |
M07630 | Error | Hand-authored write to projection table detected (forbidden) |
M07631 | Error | Projection table out of sync with model declaration |
Invariants
- AI-derived gnomons must carry status estimated, inferred, or predicted unless adjudicated by an authorized human actor. (enforced by: runtime)
- All gnomon_edge rows referencing the duplicate must be atomically rewritten to reference the canonical on merge. (enforced by: runtime)
- All writes to gnomon instances must pass through the gnomon API; direct table writes are rejected in production. (enforced by: runtime)
- Derived gnomons must carry lineage linking them to source gnomons and the derivation rule used. (enforced by: runtime)
- Every gnomon instance must carry a kind referencing a declared semantic type kind. (enforced by: runtime)
- Every gnomon instance must carry an epistemic_status drawn from the allowed enum. (enforced by: runtime)
- Every gnomon instance must have a stable internal UUID. (enforced by: runtime)
- Lineage references must be immutable after creation. (enforced by: runtime)
- On merge the duplicate gnomon’s status must be set to superseded and a lineage record created pointing to the canonical. (enforced by: runtime)
- Physical projection tables must be generated from the logical model and never hand-authored. (enforced by: compile-time + install-time)
- Relations must be stored as edge-gnomons with explicit subject, predicate, and object. (enforced by: runtime)
- Undeclared traversal paths must not be permitted in the query API. (enforced by: compile-time + runtime)
- asOf and asRecordedAt queries must not be used in preconditions or effects of action declarations. (enforced by: compile-time)
- system_time records are append-only; no UPDATE or DELETE may change a committed system_time row. (enforced by: runtime + DB-trigger)
- valid_time on Claim
fields must not be set in the past without backdated:true and a policy-authorized actor. (enforced by: runtime)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Compatibility and Migration
- MUST — Changing the canonical payload schema of a kind is a breaking change; a migration plan is required.
- MUST — Dropping a kind requires confirming no live gnomon instances exist in that kind. (proof citation:
rfc0007_b30_grounded; verification pending)
Derivation Contract
- MUST — Derived gnomons MUST be declared at the model layer, not implemented ad hoc. (proof citation:
rfc0007_derived_gnomons_at_model_layer; verification pending) - MUST — Derived gnomons MUST carry lineage back to source gnomons and the derivation rule version. (proof citation:
rfc0007_derived_gnomons_carry_lineage_with_version; verification pending) - MUST — Derived gnomons exceeding maxStaleness MUST be flagged stale and MUST NOT be surfaced unless the caller sets allowStale:true. (proof citation:
rfc0007_stale_filter_with_override; verification pending) - MUST — mode:sync MUST only be used for lightweight, deterministic derivation methods (not llm or embedding_model). (proof citation:
rfc0007_b36_grounded; verification pending)
Five Dimensions of an Gnomon
- MUST_NOT — A gnomon with epistemic_status inferred MUST NOT be treated as ground truth without explicit verification. (proof citation:
rfc0007_inferred_field_has_writing_actor; verification pending) - MAY — An gnomon MAY carry a lineage reference encoding sources, rule/model id, confidence, time range, and supersession chain. (proof citation:
rfc0007_gnomon_may_carry_lineage; verification pending) - MUST — Gnomons sharing a canonical_identity key MUST have distinct UUIDs until explicitly merged. (proof citation:
rfc0007_distinct_uuids_pre_merge; verification pending)
Generated Views
- SHOULD_NOT — Authors SHOULD NOT query the base tables directly in application code. (proof citation:
rfc0007_no_direct_base_table_queries; verification pending) - SHOULD — The runtime SHOULD generate SQL views or materialized views for common access shapes declared in the model. (proof citation:
rfc0007_views_are_generated; verification pending)
Gnomon Query API
- MUST — Implementations MUST enforce a configurable maximum on query limit (default 1000).
- MUST — Implementations MUST use the same parser as RFC-0018’s ExprContext for query predicates.
- MUST — On identity merge the duplicate gnomon’s status MUST be set to superseded with a lineage record pointing to the canonical. (proof citation:
rfc0007_merged_gnomon_carries_lineage; verification pending) - MUST — The compiler MUST emit M07622 if a predicate expression cannot be statically typed. (proof citation:
rfc0007_b50_grounded; verification pending) - MUST_NOT — The query API MUST NOT silently filter on any time dimension other than the explicit valid_time @> now() default. (proof citation:
rfc0007_b59_grounded; verification pending) - MUST_NOT — asOf and asRecordedAt queries MUST NOT be used in preconditions or effects of action declarations. (proof citation:
rfc0007_no_implicit_time_travel_in_actions; verification pending) - MUST_NOT — system_time records are append-only; no UPDATE or DELETE may change a committed system_time row. (proof citation:
rfc0007_b24_grounded; verification pending) - MUST_NOT — valid_time MUST NOT be set in the past for Claim
fields without an explicit backdated:true flag and a policy-authorized actor. (proof citation: rfc0007_backdating_requires_capability; verification pending)
Invariants
- MUST — Derived gnomons MUST carry lineage linking them to source gnomons and the derivation rule used. (proof citation:
rfc0007_derived_gnomons_carry_lineage; verification pending) - MUST — Every gnomon instance MUST carry a kind referencing a declared semantic type kind. (proof citation:
rfc0007_every_gnomon_has_kind; verification pending) - MUST — Every gnomon instance MUST carry an epistemic_status from the allowed set. (proof citation:
rfc0007_every_gnomon_has_epistemic_status; verification pending) - MUST — Every gnomon instance MUST have a stable internal UUID. (proof citation:
rfc0007_stable_internal_uuid; verification pending) - MUST_NOT — Physical projection tables MUST be generated from the logical model and MUST NOT be hand-authored. (proof citation:
rfc0007_b26_grounded; verification pending) - MUST — Relations MUST be stored as edge-gnomons with explicit subject, predicate, and object. (proof citation:
rfc0007_relations_as_edge_gnomons; verification pending)
Physical Storage Strategy
- MUST_NOT — A claim field MUST NOT use different storage strategies across module versions without a migration operation.
- MUST — An AI agent writing a claim field MUST have the writing action listed in its permissions block. (proof citation:
rfc0007_b40_grounded; verification pending) - MUST_NOT — Authors MUST NOT manage both the support-table and projection-column embedding paths manually. (proof citation:
rfc0007_storage_paths_are_generated; verification pending) - MUST — Authors MUST NOT write to projection tables directly; all writes go through the gnomon API. (proof citation:
rfc0007_writes_via_gnomon_api; verification pending) - MUST — Projection tables MUST have generated indexes on
_conf and _status when confidence-threshold policies are declared. (proof citation: rfc0007_confidence_indexes_generated; verification pending) - MUST — The _claim:true sentinel MUST be present on inline-stored claim fields so the kernel can distinguish them without schema lookup.
- MUST — The compiler MUST emit the selected claim storage strategy in the storage manifest. (proof citation:
rfc0007_storage_manifest_generated; verification pending) - MUST — The kernel MUST enforce required_evidence, allowed_status, and min_confidence_to_use constraints at claim write time. (proof citation:
rfc0007_claim_constraints_at_boundary; verification pending) - MUST — The query API MUST be partition-transparent — callers MUST NOT need to know which partition holds an gnomon.
- MUST — When a claim field declares min_confidence_to_use or is referenced in queries, the compiler MUST generate explicit evidence columns in the projection table. (proof citation:
rfc0007_evidence_columns_generated; verification pending)
Relation Declarations
- MUST — Relations MUST be declared once at the model layer; the framework generates accessors, joins, and API fields. (proof citation:
rfc0007_relations_at_model_layer; verification pending) - MUST_NOT — Undeclared traversal paths MUST NOT be permitted in the query API. (proof citation:
rfc0007_no_undeclared_traversals; verification pending)
Security and Authorization
- MUST — AI-derived gnomons MUST carry status estimated, inferred, or predicted unless adjudicated by an authorized human actor. (proof citation:
rfc0007_b66_grounded; verification pending) - MUST — All writes to gnomon instances MUST pass through the gnomon API; direct table writes MUST be rejected in production. (proof citation:
rfc0007_all_writes_through_api; verification pending) - MUST — Epistemic status MUST be set by the writing actor, not derived post-hoc by a separate process. (proof citation:
rfc0007_epistemic_status_set_by_writing_actor; verification pending) - MUST — Lineage references MUST be immutable after creation. (proof citation:
rfc0007_lineage_id_stable; verification pending)
Three-Layer Logical Model
- SHOULD — Domain-meaningful relations SHOULD be modeled as edge-gnomons with their own identity rather than bare foreign keys. (proof citation:
rfc0007_relations_as_edge_gnomons; verification pending)
Linked References
(no cross-RFC dependencies)