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.
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
| Term | Meaning |
|---|---|
| Entity-type view | A read-only SQL view filtered to one entity-type’s kind, with typed column extraction. |
| Expression index | A PG index over a JSONB extraction expression, providing the planner real selectivity statistics. |
| Field schema | The typed field declarations on an entity-type; each field maps to one extracted column. |
| INSTEAD OF trigger | A PG trigger on a view that intercepts writes; Phase 2 routes view writes through the gnomon pipeline. |
| Materialized view | A PG materialized view (a real table backed by a query) used for hot read paths; owns its own RLS. |
| Security barrier view | A PG view created WITH (security_barrier = true), preventing the planner from pushing user-supplied predicates below the view’s WHERE clause. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M53010 | Error | Index name collision: two declarations would emit the same index name with different definitions |
M53011 | Warning | Index emitted is duplicative — same expression index already exists on graph.resource |
M53020 | Error | Entity-type field type has no PG type mapping; add to type-mapping table |
M53021 | Warning | Field declared indexed: true with a type that doesn’t support B-tree; using fallback index strategy |
M53030 | Error | View recreation would orphan data: a column removal without a corresponding core.migrations.RemoveField migration |
M53040 | Error | INSTEAD OF trigger missing required template-marker setup; view writes will fail RLS check |
M53041 | Error | INSTEAD OF trigger validation function missing or incomplete |
M53050 | Warning | Cross-module join view declared with predicate not in the dependency closure of either module |
M53060 | Warning | Materialization requested for an entity-type with high write rate; consider live view instead |
M53070 | Error | View 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
- Cross-module joins go through graph.statement and never through synthesized cross-schema FK constraints. (enforced by: compile-time)
- Every entity-type view MUST be created WITH (security_barrier = true). (enforced by: compile-time)
- INSTEAD OF triggers MUST run entity-type validation (required fields, enums, custom hooks) before write. (enforced by: runtime)
- INSTEAD OF triggers MUST set gnomon.template_marker before invoking graph procedures. (enforced by: runtime + RLS)
- Index naming follows the idx_
_ pattern with collisions diagnosed as M53010. (enforced by: compile-time) - Standard views inherit RLS from graph.resource while materialized views own their own RLS policies. (enforced by: RLS)
- View column names use snake_case and module schema names replace dots with underscores. (enforced by: compile-time)
- 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
- 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
- MUST — Cross-module joins go through graph.statement — never through synthesized cross-schema FK constraints. (proof citation:
rfc0053_b0_grounded; verification pending) - MUST — Every entity-type view is created WITH (security_barrier = true).
- MUST — INSTEAD OF triggers MUST run entity-type validation before write.
- MUST — INSTEAD OF triggers MUST set gnomon.template_marker before invoking graph procedures.
- MUST — Index naming follows the pattern idx_
_ . - MUST — Standard views inherit RLS from graph.resource; materialized views own their own RLS.
- MUST — View column names use snake_case; module schema names replace ’.’ with ’_’.
- MUST — View regeneration is part of the install plan and gates destructive operations per KP26.
Lifecycle and Rebuilding
- SHOULD — The install plan SHOULD use CREATE INDEX CONCURRENTLY for production index additions.
Phase 2: Write-Through via INSTEAD OF Triggers
- MUST — INSTEAD OF triggers MUST run the entity-type’s compile-time validation before invoking graph.create_resource.
- MUST — Phase 2 INSTEAD OF triggers MUST set the gnomon.template_marker GUC before invoking graph.create_resource.
Security Barrier and RLS Inheritance
- MUST — Every entity-type view MUST be created WITH (security_barrier = true).
- 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
- 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
| Direction | Target |
|---|---|
| Depends on | RFC-0001 |
| Depends on | RFC-0005 |
| Depends on | RFC-0006 |
| Depends on | RFC-0007 |
| Depends on | RFC-0008 |
| Depends on | RFC-0010 |
| Depends on | RFC-0024 |
| Depends on | RFC-0033 |
| Depends on | RFC-0036 |
| Depends on | RFC-0037 |
| Depends on | RFC-0038 |
| Depends on | RFC-0039 |
| Depends on | RFC-0040 |
| Depends on | RFC-0041 |
| Depends on | RFC-0042 |
| Depends on | RFC-0048 |
| Depends on | RFC-0049 |
| Depends on | RFC-0051 |
| Depends on | RFC-0052 |