RFC-0051 · 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-0051: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0051.This page is generated from the
lean/Gnomon/Spec/module for RFC-0051. Edit that source and regenerate this catalog.
Title: PostgreSQL Storage Adapter
Status: draft
Owners: Graph Platform, Storage
Diagnostic range: M51000-M51099
Depends on: RFC-0001, RFC-0006, RFC-0007, RFC-0008, RFC-0010, RFC-0024, RFC-0033, RFC-0036, RFC-0037, RFC-0038, RFC-0039, RFC-0040, RFC-0042, RFC-0048
Extended by: RFC-0052, RFC-0053, RFC-0054
Proof citations in source: 3 / 3. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| Adapter | The Postgres-specific implementation of RFC-0037’s GraphBackend interfaces. |
| Bootstrap.sql | The committed SQL artifact (KP24) that creates the minimal Phase-1 schema needed before the install pipeline can run. |
| GUC | A PostgreSQL Grand Unified Configuration parameter — session-bound key-value state used to carry runtime context. |
| Module schema | A PostgreSQL schema named after a module’s namespace (savvi.studio.team → savvi_studio_team), used as the container for the module’s view-mapping outputs. |
| Platform schema | One of the six PostgreSQL schemas this adapter installs at bootstrap: graph, audit, auth, ids, queries, webhook. |
| Reserved namespace | An ltree path under which only privileged paths may create gnomons (graph., core.). |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M51010 | Fatal | Required PostgreSQL extension is not installed (ltree, pgcrypto, uuid-ossp, hstore) |
M51011 | Fatal | Bootstrap format version mismatch — adapter cannot operate against this DB instance |
M51012 | Fatal | Platform schema or owner role missing from the database after bootstrap |
M51020 | Defect | graph.has_permission PG implementation diverges from RFC-0042 §4.2 evaluation |
M51021 | Warning | RLS policy fired during a privileged-write path; defense-in-depth caught a defect |
M51030 | Error | Application module attempted to add to graph.reserved_namespaces |
M51040 | Error | bootstrap.sql regeneration produced a diff against committed artifact |
M51050 | Warning | gnomon.template_marker GUC not set during a graph write |
M51060 | Error | Per-module PG role missing during install; install pipeline cannot SET ROLE |
M51070 | Warning | Module schema name collision: namespace-derived schema already exists with different owner |
Dependency neighborhood
graph LR
nRFC_0051["RFC-0051"]
nRFC_0001["RFC-0001"]
nRFC_0051 --> nRFC_0001
nRFC_0006["RFC-0006"]
nRFC_0051 --> nRFC_0006
nRFC_0007["RFC-0007"]
nRFC_0051 --> nRFC_0007
nRFC_0008["RFC-0008"]
nRFC_0051 --> nRFC_0008
nRFC_0010["RFC-0010"]
nRFC_0051 --> nRFC_0010
nRFC_0024["RFC-0024"]
nRFC_0051 --> nRFC_0024
nRFC_0033["RFC-0033"]
nRFC_0051 --> nRFC_0033
nRFC_0036["RFC-0036"]
nRFC_0051 --> nRFC_0036
nRFC_0037["RFC-0037"]
nRFC_0051 --> nRFC_0037
nRFC_0038["RFC-0038"]
nRFC_0051 --> nRFC_0038
nRFC_0039["RFC-0039"]
nRFC_0051 --> nRFC_0039
nRFC_0040["RFC-0040"]
nRFC_0051 --> nRFC_0040
nRFC_0042["RFC-0042"]
nRFC_0051 --> nRFC_0042
nRFC_0048["RFC-0048"]
nRFC_0051 --> nRFC_0048
nRFC_0052["RFC-0052"]
nRFC_0052 --> nRFC_0051
nRFC_0053["RFC-0053"]
nRFC_0053 --> nRFC_0051
nRFC_0054["RFC-0054"]
nRFC_0054 --> nRFC_0051
Invariants
- After bootstrap the six platform schemas exist with their declared owner roles. (enforced by: install-time)
- Application modules must not add entries to graph.reserved_namespaces; the table is bootstrap-only. (enforced by: compile-time)
- Kind is immutable after creation; the SH1 trigger rejects any UPDATE that changes kind. (enforced by: DB-trigger)
- RFC-0037 service queries map deterministically to PG function calls per RFC-0051. (enforced by: compile-time)
- RLS gates direct INSERT into graph.* and core.* kinds unless gnomon.template_marker is set or the session is admin. (enforced by: RLS)
- Resource and statement IDs are generated by the Snowflake-style ids.gen_*_id() functions. (enforced by: DB-default)
- Session GUCs (app.current_user_id, app.current_user_type, app.is_admin) are set at the start of every request transaction. (enforced by: runtime)
- The adapter requires ltree, pgcrypto, uuid-ossp, and hstore extensions to be installed before boot. (enforced by: boot-time)
- bootstrap.sql is regenerated by CI and verified by diff against the committed artifact. (enforced by: CI)
- graph.has_permission matches the RFC-0042 evaluation algorithm exactly. (enforced by: runtime)
- graph.resource and graph.statement schemas match the legacy DDL exactly. (enforced by: compile-time)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Bootstrap.sql Contract
- MUST — CI must regenerate bootstrap.sql from current source and fail on diff. (proof citation:
rfc0051_b3_grounded; verification pending)
Compatibility and Migration
- MUST — The runtime must set and clear gnomon.template_marker around template executions.
Distributed ID Generation
- MUST — Sum of timestamp + machine + sequence bits must equal 63.
- MAY — The install engine may allocate ID ranges per module via deterministic machine_id derived from the manifest hash.
Platform Schemas
- MAY — Development deployments may use a single connector role with module-scoped GUC and RLS checks.
- MUST — Production deployments must use dedicated PG roles per module schema.
PostgreSQL Extensions
- MUST — Refuse to boot if any required PostgreSQL extension is unavailable. (proof citation:
rfc0051_b8_grounded; verification pending) - MUST — Required extensions must be installed by a privileged operator before the adapter’s first boot.
RLS Contract
- MUST — graph.has_permission must match the RFC-0042 §4.2 evaluation algorithm exactly. (proof citation:
rfc0051_b5_grounded; verification pending)
Reserved Namespaces
- MUST_NOT — Application modules must not add entries to graph.reserved_namespaces.
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0001 |
| 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-0042 |
| Depends on | RFC-0048 |
| Extended by | RFC-0052 |
| Extended by | RFC-0053 |
| Extended by | RFC-0054 |