gnomonlearn
Docs/RFC-0051/Reference catalog

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.

← Read the authored RFC

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

TermMeaning
AdapterThe Postgres-specific implementation of RFC-0037’s GraphBackend interfaces.
Bootstrap.sqlThe committed SQL artifact (KP24) that creates the minimal Phase-1 schema needed before the install pipeline can run.
GUCA PostgreSQL Grand Unified Configuration parameter — session-bound key-value state used to carry runtime context.
Module schemaA 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 schemaOne of the six PostgreSQL schemas this adapter installs at bootstrap: graph, audit, auth, ids, queries, webhook.
Reserved namespaceAn ltree path under which only privileged paths may create gnomons (graph., core.).

Diagnostics

CodeSeverityDescription
M51010FatalRequired PostgreSQL extension is not installed (ltree, pgcrypto, uuid-ossp, hstore)
M51011FatalBootstrap format version mismatch — adapter cannot operate against this DB instance
M51012FatalPlatform schema or owner role missing from the database after bootstrap
M51020Defectgraph.has_permission PG implementation diverges from RFC-0042 §4.2 evaluation
M51021WarningRLS policy fired during a privileged-write path; defense-in-depth caught a defect
M51030ErrorApplication module attempted to add to graph.reserved_namespaces
M51040Errorbootstrap.sql regeneration produced a diff against committed artifact
M51050Warninggnomon.template_marker GUC not set during a graph write
M51060ErrorPer-module PG role missing during install; install pipeline cannot SET ROLE
M51070WarningModule 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

  1. After bootstrap the six platform schemas exist with their declared owner roles. (enforced by: install-time)
  2. Application modules must not add entries to graph.reserved_namespaces; the table is bootstrap-only. (enforced by: compile-time)
  3. Kind is immutable after creation; the SH1 trigger rejects any UPDATE that changes kind. (enforced by: DB-trigger)
  4. RFC-0037 service queries map deterministically to PG function calls per RFC-0051. (enforced by: compile-time)
  5. RLS gates direct INSERT into graph.* and core.* kinds unless gnomon.template_marker is set or the session is admin. (enforced by: RLS)
  6. Resource and statement IDs are generated by the Snowflake-style ids.gen_*_id() functions. (enforced by: DB-default)
  7. 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)
  8. The adapter requires ltree, pgcrypto, uuid-ossp, and hstore extensions to be installed before boot. (enforced by: boot-time)
  9. bootstrap.sql is regenerated by CI and verified by diff against the committed artifact. (enforced by: CI)
  10. graph.has_permission matches the RFC-0042 evaluation algorithm exactly. (enforced by: runtime)
  11. 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

  1. MUST — CI must regenerate bootstrap.sql from current source and fail on diff. (proof citation: rfc0051_b3_grounded; verification pending)

Compatibility and Migration

  1. MUST — The runtime must set and clear gnomon.template_marker around template executions.

Distributed ID Generation

  1. MUST — Sum of timestamp + machine + sequence bits must equal 63.
  2. MAY — The install engine may allocate ID ranges per module via deterministic machine_id derived from the manifest hash.

Platform Schemas

  1. MAY — Development deployments may use a single connector role with module-scoped GUC and RLS checks.
  2. MUST — Production deployments must use dedicated PG roles per module schema.

PostgreSQL Extensions

  1. MUST — Refuse to boot if any required PostgreSQL extension is unavailable. (proof citation: rfc0051_b8_grounded; verification pending)
  2. MUST — Required extensions must be installed by a privileged operator before the adapter’s first boot.

RLS Contract

  1. MUST — graph.has_permission must match the RFC-0042 §4.2 evaluation algorithm exactly. (proof citation: rfc0051_b5_grounded; verification pending)

Reserved Namespaces

  1. MUST_NOT — Application modules must not add entries to graph.reserved_namespaces.

Linked References

DirectionTarget
Depends onRFC-0001
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-0042
Depends onRFC-0048
Extended byRFC-0052
Extended byRFC-0053
Extended byRFC-0054