gnomonlearn
Docs/RFC-0053/Reference catalog

RFC-0053 · 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-0053: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in RFC-0053.

This page is generated from the lean/Gnomon/Spec/ module for RFC-0053. Edit that source and regenerate this catalog.


Title: View-Mapping Layer
Status: draft
Owners: Compiler, Storage
Diagnostic range: M53000-M53099

Depends on: RFC-0001, RFC-0005, RFC-0006, RFC-0007, RFC-0008, RFC-0010, RFC-0024, RFC-0033, RFC-0036, RFC-0037, RFC-0038, RFC-0039, RFC-0040, RFC-0041, RFC-0042, RFC-0048, RFC-0049, RFC-0051, RFC-0052

Proof citations in source: 4 / 4. Standalone proof verification is pending.


Definitions

TermMeaning
Entity-type viewA read-only SQL view filtered to one entity-type’s kind, with typed column extraction.
Expression indexA PG index over a JSONB extraction expression, providing the planner real selectivity statistics.
Field schemaThe typed field declarations on an entity-type; each field maps to one extracted column.
INSTEAD OF triggerA PG trigger on a view that intercepts writes; Phase 2 routes view writes through the gnomon pipeline.
Materialized viewA PG materialized view (a real table backed by a query) used for hot read paths; owns its own RLS.
Security barrier viewA PG view created WITH (security_barrier = true), preventing the planner from pushing user-supplied predicates below the view’s WHERE clause.

Diagnostics

CodeSeverityDescription
M53010ErrorIndex name collision: two declarations would emit the same index name with different definitions
M53011WarningIndex emitted is duplicative — same expression index already exists on graph.resource
M53020ErrorEntity-type field type has no PG type mapping; add to type-mapping table
M53021WarningField declared indexed: true with a type that doesn’t support B-tree; using fallback index strategy
M53030ErrorView recreation would orphan data: a column removal without a corresponding core.migrations.RemoveField migration
M53040ErrorINSTEAD OF trigger missing required template-marker setup; view writes will fail RLS check
M53041ErrorINSTEAD OF trigger validation function missing or incomplete
M53050WarningCross-module join view declared with predicate not in the dependency closure of either module
M53060WarningMaterialization requested for an entity-type with high write rate; consider live view instead
M53070ErrorView name collision: two entity-types in the same module would emit the same view name

Dependency neighborhood

graph LR
  nRFC_0053["RFC-0053"]
  nRFC_0001["RFC-0001"]
  nRFC_0053 --> nRFC_0001
  nRFC_0005["RFC-0005"]
  nRFC_0053 --> nRFC_0005
  nRFC_0006["RFC-0006"]
  nRFC_0053 --> nRFC_0006
  nRFC_0007["RFC-0007"]
  nRFC_0053 --> nRFC_0007
  nRFC_0008["RFC-0008"]
  nRFC_0053 --> nRFC_0008
  nRFC_0010["RFC-0010"]
  nRFC_0053 --> nRFC_0010
  nRFC_0024["RFC-0024"]
  nRFC_0053 --> nRFC_0024
  nRFC_0033["RFC-0033"]
  nRFC_0053 --> nRFC_0033
  nRFC_0036["RFC-0036"]
  nRFC_0053 --> nRFC_0036
  nRFC_0037["RFC-0037"]
  nRFC_0053 --> nRFC_0037
  nRFC_0038["RFC-0038"]
  nRFC_0053 --> nRFC_0038
  nRFC_0039["RFC-0039"]
  nRFC_0053 --> nRFC_0039
  nRFC_0040["RFC-0040"]
  nRFC_0053 --> nRFC_0040
  nRFC_0041["RFC-0041"]
  nRFC_0053 --> nRFC_0041
  nRFC_0042["RFC-0042"]
  nRFC_0053 --> nRFC_0042
  nRFC_0048["RFC-0048"]
  nRFC_0053 --> nRFC_0048
  nRFC_0049["RFC-0049"]
  nRFC_0053 --> nRFC_0049
  nRFC_0051["RFC-0051"]
  nRFC_0053 --> nRFC_0051
  nRFC_0052["RFC-0052"]
  nRFC_0053 --> nRFC_0052

Invariants

  1. Cross-module joins go through graph.statement and never through synthesized cross-schema FK constraints. (enforced by: compile-time)
  2. Every entity-type view MUST be created WITH (security_barrier = true). (enforced by: compile-time)
  3. INSTEAD OF triggers MUST run entity-type validation (required fields, enums, custom hooks) before write. (enforced by: runtime)
  4. INSTEAD OF triggers MUST set gnomon.template_marker before invoking graph procedures. (enforced by: runtime + RLS)
  5. Index naming follows the idx__ pattern with collisions diagnosed as M53010. (enforced by: compile-time)
  6. Standard views inherit RLS from graph.resource while materialized views own their own RLS policies. (enforced by: RLS)
  7. View column names use snake_case and module schema names replace dots with underscores. (enforced by: compile-time)
  8. View regeneration is part of the install plan with destructive operations gated per KP26. (enforced by: install-time)

Normative Statements

Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.

Cross-Module Joins

  1. MAY — Modules MAY pre-declare join views for frequently-joined entity-type pairs via a view declaration. (proof citation: rfc0053_b16_grounded; verification pending)

Invariants

  1. MUST — Cross-module joins go through graph.statement — never through synthesized cross-schema FK constraints. (proof citation: rfc0053_b0_grounded; verification pending)
  2. MUST — Every entity-type view is created WITH (security_barrier = true).
  3. MUST — INSTEAD OF triggers MUST run entity-type validation before write.
  4. MUST — INSTEAD OF triggers MUST set gnomon.template_marker before invoking graph procedures.
  5. MUST — Index naming follows the pattern idx__.
  6. MUST — Standard views inherit RLS from graph.resource; materialized views own their own RLS.
  7. MUST — View column names use snake_case; module schema names replace ’.’ with ’_’.
  8. MUST — View regeneration is part of the install plan and gates destructive operations per KP26.

Lifecycle and Rebuilding

  1. SHOULD — The install plan SHOULD use CREATE INDEX CONCURRENTLY for production index additions.

Phase 2: Write-Through via INSTEAD OF Triggers

  1. MUST — INSTEAD OF triggers MUST run the entity-type’s compile-time validation before invoking graph.create_resource.
  2. MUST — Phase 2 INSTEAD OF triggers MUST set the gnomon.template_marker GUC before invoking graph.create_resource.

Security Barrier and RLS Inheritance

  1. MUST — Every entity-type view MUST be created WITH (security_barrier = true).
  2. MAY — The framework MAY materialize an entity-type view as a real table when read patterns justify it. (proof citation: rfc0053_b10_grounded; verification pending)

Type Mapping

  1. MUST — New types added to the Gnomon type model MUST extend the PG type-mapping table. (proof citation: rfc0053_b12_grounded; verification pending)

Linked References

DirectionTarget
Depends onRFC-0001
Depends onRFC-0005
Depends onRFC-0006
Depends onRFC-0007
Depends onRFC-0008
Depends onRFC-0010
Depends onRFC-0024
Depends onRFC-0033
Depends onRFC-0036
Depends onRFC-0037
Depends onRFC-0038
Depends onRFC-0039
Depends onRFC-0040
Depends onRFC-0041
Depends onRFC-0042
Depends onRFC-0048
Depends onRFC-0049
Depends onRFC-0051
Depends onRFC-0052