gnomonlearn
Docs/RFC-0007/Reference catalog

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.

← Read the authored RFC

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

TermMeaning
Epistemic StatusConfidence/provenance posture of a value: asserted, observed, inferred, estimated, predicted, disputed, or superseded.
Gnomon KindsLayer 1 — semantic types declared in the authoring layer that application code and AI workflows address.
Gnomon ProjectionsLayer 3 — optimized physical views (relational, document, embedding, search, timeline, API) of the logical model.
Gnomon RelationsLayer 2 — first-class typed semantic edges between gnomon instances carrying qualifiers and confidence.
IdentityA stable UUID assigned at gnomon creation; merge is an explicit lifecycle operation.
Identity MergeExplicit lifecycle operation that retires a duplicate gnomon in favor of a canonical one, requiring authorization.
LineageReference encoding source gnomon IDs, derivation rule/model ID/version, confidence, timestamp range, and supersession chain.
Representation SetMultiple physical representations of the same semantic content, derived from an authoritative canonical payload.
Semantic KindThe declared type of an gnomon’s content drawn from pg_gnomon_kind, determining operators, indexing, and validation.
asOf queryRead primitive returning the state of the object graph at a past or future valid_time point.
asRecordedAt queryAudit read primitive returning what the database contained at a past transaction (system_time) point.
system_timeInternal append-only time range during which a row existed in the database.
valid_timeUser-visible time range during which an gnomon’s value is considered true in the domain.

Diagnostics

CodeSeverityDescription
M07030ErrorClaim write missing required evidence field
M07031ErrorClaim write uses status value not in allowed_status
M07032ErrorClaim storage strategy changed between versions without migration operation
M07033ErrorClaim field below min_confidence_to_use surfaced in query result (runtime enforcement gap)
M07034ErrorKernel claim enforcement skipped — claim declaration not found in module registry
M07600ErrorGnomon created without kind declaration
M07601ErrorCanonical identity collision detected on merge — conflicting canonical instances
M07602ErrorActor not authorized to merge gnomons of this kind
M07603ErrorMerge attempted on gnomon already marked superseded
M07610ErrorTraversal path references undeclared relation
M07611ErrorEdge created with subject/object kind mismatch against declared relation
M07620ErrorDerived gnomon missing lineage reference
M07621WarningStale derived gnomon detected — source updated beyond maxStaleness window
M07622Errormode:sync declared on non-deterministic derivation method (llm, embedding_model)
M07630ErrorHand-authored write to projection table detected (forbidden)
M07631ErrorProjection table out of sync with model declaration

Invariants

  1. AI-derived gnomons must carry status estimated, inferred, or predicted unless adjudicated by an authorized human actor. (enforced by: runtime)
  2. All gnomon_edge rows referencing the duplicate must be atomically rewritten to reference the canonical on merge. (enforced by: runtime)
  3. All writes to gnomon instances must pass through the gnomon API; direct table writes are rejected in production. (enforced by: runtime)
  4. Derived gnomons must carry lineage linking them to source gnomons and the derivation rule used. (enforced by: runtime)
  5. Every gnomon instance must carry a kind referencing a declared semantic type kind. (enforced by: runtime)
  6. Every gnomon instance must carry an epistemic_status drawn from the allowed enum. (enforced by: runtime)
  7. Every gnomon instance must have a stable internal UUID. (enforced by: runtime)
  8. Lineage references must be immutable after creation. (enforced by: runtime)
  9. On merge the duplicate gnomon’s status must be set to superseded and a lineage record created pointing to the canonical. (enforced by: runtime)
  10. Physical projection tables must be generated from the logical model and never hand-authored. (enforced by: compile-time + install-time)
  11. Relations must be stored as edge-gnomons with explicit subject, predicate, and object. (enforced by: runtime)
  12. Undeclared traversal paths must not be permitted in the query API. (enforced by: compile-time + runtime)
  13. asOf and asRecordedAt queries must not be used in preconditions or effects of action declarations. (enforced by: compile-time)
  14. system_time records are append-only; no UPDATE or DELETE may change a committed system_time row. (enforced by: runtime + DB-trigger)
  15. 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

  1. MUST — Changing the canonical payload schema of a kind is a breaking change; a migration plan is required.
  2. MUST — Dropping a kind requires confirming no live gnomon instances exist in that kind. (proof citation: rfc0007_b30_grounded; verification pending)

Derivation Contract

  1. MUST — Derived gnomons MUST be declared at the model layer, not implemented ad hoc. (proof citation: rfc0007_derived_gnomons_at_model_layer; verification pending)
  2. 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)
  3. 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)
  4. 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

  1. 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)
  2. 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)
  3. 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

  1. SHOULD_NOT — Authors SHOULD NOT query the base tables directly in application code. (proof citation: rfc0007_no_direct_base_table_queries; verification pending)
  2. 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

  1. MUST — Implementations MUST enforce a configurable maximum on query limit (default 1000).
  2. MUST — Implementations MUST use the same parser as RFC-0018’s ExprContext for query predicates.
  3. 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)
  4. MUST — The compiler MUST emit M07622 if a predicate expression cannot be statically typed. (proof citation: rfc0007_b50_grounded; verification pending)
  5. 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)
  6. 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)
  7. 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)
  8. 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

  1. 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)
  2. MUST — Every gnomon instance MUST carry a kind referencing a declared semantic type kind. (proof citation: rfc0007_every_gnomon_has_kind; verification pending)
  3. MUST — Every gnomon instance MUST carry an epistemic_status from the allowed set. (proof citation: rfc0007_every_gnomon_has_epistemic_status; verification pending)
  4. MUST — Every gnomon instance MUST have a stable internal UUID. (proof citation: rfc0007_stable_internal_uuid; verification pending)
  5. 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)
  6. 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

  1. MUST_NOT — A claim field MUST NOT use different storage strategies across module versions without a migration operation.
  2. 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)
  3. 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)
  4. 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)
  5. 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)
  6. MUST — The _claim:true sentinel MUST be present on inline-stored claim fields so the kernel can distinguish them without schema lookup.
  7. MUST — The compiler MUST emit the selected claim storage strategy in the storage manifest. (proof citation: rfc0007_storage_manifest_generated; verification pending)
  8. 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)
  9. MUST — The query API MUST be partition-transparent — callers MUST NOT need to know which partition holds an gnomon.
  10. 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

  1. 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)
  2. MUST_NOT — Undeclared traversal paths MUST NOT be permitted in the query API. (proof citation: rfc0007_no_undeclared_traversals; verification pending)

Security and Authorization

  1. 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)
  2. 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)
  3. 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)
  4. MUST — Lineage references MUST be immutable after creation. (proof citation: rfc0007_lineage_id_stable; verification pending)

Three-Layer Logical Model

  1. 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)