gnomonlearn
Docs/PostgreSQL/RFC-0052

RFC-0052 · Platform Module 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.

Status Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release.

View the generated reference catalog →

Read design questions and decisions →


Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.


1. Purpose

Gnomon’s platform is itself composed as a set of Gnomon modules. The graph runtime, audit framework, auth subsystem, ID generators, and webhook layer are not built into the kernel — they are platform modules with normal module.gnm manifests, normal install pipelines, and normal version semantics. The kernel’s only built-in artifact is the bootstrap loader (RFC-0051 §12), which is itself a generated output of these modules.

This RFC names the platform modules, specifies their boundaries, declares their install order, and defines the cross-module template-call surface that ties them together. It is the bridge between the abstract Gnomon data model (RFC-0036) and the concrete, multi-module decomposition that operates the system.

The platform catalog has two namespaces:

  • db.* — physical storage modules. Each owns one PostgreSQL schema. They install schemas, tables, functions, triggers, and views.
  • core.* — structural meta-gnomon modules. They declare the kind-definitions, predicate-policies, modules, templates, entity-types, aspects, facets, etc. that user modules build on.

Together these form the complete platform substrate. Application modules (savvi.*, ext.*, etc.) install on top of them.


2. Definitions

TermMeaning
Platform moduleA module in the db.* or core.* namespace that contributes to the runtime substrate.
Application moduleAny non-platform module — savvi.*, ext.*, customer-namespaced modules.
Bootstrap moduleA platform module whose install runs through Phase 1 (bootstrap.sql) rather than the normal install pipeline. Currently: db.graph (partial), db.ids, db.audit core.
Layered moduleA platform module that extends another via the extends protocol (RFC-0024 §6.2 generalized) — e.g., core.graph.collection extending core.graph.
Install rankThe ordinal position of a module in the install DAG. Determined by dependency closure.

3. The db.* Layer (Physical Storage)

Eight modules. Each owns one PostgreSQL schema and contributes the DDL that creates its tables, functions, triggers, and views.

3.1 db.pg — meta-module (no PG schema)

Purpose: the type system and DDL primitives that other db.* modules use to declare their physical artifacts. db.pg is a meta-module: it contributes 28 PG base types (with schema.org supertypes), 12 column aspects (timestamps, soft-delete, audited-creator, etc.), and 9 DDL templates (table, column, function, enum, domain, composite, policy, trigger, index).

Owns: no PG schema; declares only meta-gnomons.

Key declarations:

  • db.pg.int8, db.pg.text, db.pg.bool, db.pg.timestamptz, db.pg.jsonb, db.pg.ltree, db.pg.uuid (and 21 others)
  • db.pg.aspect.timestamps, db.pg.aspect.soft-delete, db.pg.aspect.audited-creator, db.pg.aspect.data-jsonb, db.pg.aspect.bigint-pk, etc.
  • db.pg.template.table, db.pg.template.column, db.pg.template.function, db.pg.template.enum, db.pg.template.domain, db.pg.template.composite, db.pg.template.policy, db.pg.template.trigger, db.pg.template.index
  • db.pg.role declarations: studio_app_connector, studio_migrator, studio_admin, schema-owner roles

Dependencies: core (for kind-definitions).

Install rank: 1 (after bootstrap, before any other db.* module).

3.2 db.ids — distributed identity

Purpose: Snowflake-compatible distributed ID generation.

Owns PG schema: ids (no specific owner role; functions are SECURITY DEFINER).

Key declarations:

  • ids.id_config composite type
  • ids.generator_metadata table
  • ids.dns_label, ids.dns_name, ids.pg_identifier, ids.bit_count domains
  • ids.create_generator(name, config) function
  • ids.gen_resource_id(), ids.gen_statement_id() (declared here; bootstrap function bodies)

Dependencies: db.pg.

Install rank: 2.

3.3 db.audit — universal audit framework

Purpose: tamper-evident change tracking for any table.

Owns PG schema: audit (owner: studio_audit_owner).

Key declarations:

  • audit.events table (1 table)
  • audit.install_audit_trigger(regclass) — adds trigger to a table
  • audit.purge_old_events(before_timestamp) — retention helper
  • audit.uninstall_audit_trigger(regclass) — removal
  • 12 other internal helpers

Dependencies: db.pg, db.ids.

Install rank: 3 (db.graph depends on this for trigger installation).

3.4 db.graph — the graph runtime

Purpose: the universal gnomon store and runtime. Tables, RLS, traversal, collections, permissions.

Owns PG schema: graph (owner: studio_graph_owner).

Key declarations:

  • graph.resource, graph.statement (the carrier — RFC-0036 §4)
  • graph.predicate_policy, graph.resource_policy, graph.statement_policy (RFC-0042)
  • graph.permission_cache (RFC-0036 §6.2)
  • graph.external_link (RFC-0036 §6.4)
  • graph.reserved_namespaces (RFC-0051 §8)
  • graph.has_permission(), graph.set_session_user(), graph.is_admin_session(), graph.current_user_id(), graph.current_user_type()
  • graph.create_resource(), graph.create_statement(), all RFC-0037 service implementations
  • RLS policies on graph.resource and graph.statement (RFC-0051 §7.3)
  • SH1/SH2 triggers (RFC-0051 §7.4)
  • graph.collection_type enum, graph.traversal_direction enum
  • graph.resource_input, graph.statement_input composites

Dependencies: db.pg, db.ids, db.audit.

Install rank: 4. Partially in bootstrap.sql — the table creates and basic RLS are bootstrapped (Phase 1); functions and indexes are installed by the normal pipeline (Phase 2).

3.5 db.auth — authentication and authorization storage

Purpose: sessions, secrets, JWT verification, key rotation.

Owns PG schema: auth (owner: studio_auth_owner).

Key declarations:

  • auth.sessions, auth.secrets, auth.key_rotations, auth.key_rotation_members, auth.secrets_audit_log (5 of 12 tables)
  • auth.validations, auth.algorithms (validation framework)
  • auth.jwt_expected_audiences, auth.jwt_claim_mappings, auth.jwt_issuer_mappings, auth.jwt_role_mappings, auth.jwt_revocations (JWT framework)
  • auth.subject_id(), auth.verify_jwt(), auth.session_active() and 93 other functions
  • auth.rotation_schedule_type, auth.key_type, auth.jwt_verify_result types

Dependencies: db.pg, db.ids, db.audit.

Install rank: 5.

Implements: RFC-0048 (Principal & Session Model) — provides the storage backing.

3.6 db.queries — shared query subsystem

Purpose: shared query helpers used across modules.

Owns PG schema: queries (owner: studio_queries_owner).

Key declarations: 5 functions; no tables.

Dependencies: db.pg.

Install rank: 5 (parallel with db.auth).

3.7 db.util — common helpers

Purpose: shared SQL utility functions.

Owns PG schema: util (owner: per-utility, varies).

Key declarations: 2 small tables (config keys, registries), 35 utility functions.

Dependencies: db.pg.

Install rank: 5 (parallel).

3.8 db.webhook — webhook subsystem

Purpose: inbound webhook handling, provider registration, event routing.

Owns PG schema: webhook (owner: studio_webhook_owner).

Key declarations:

  • webhook.providers, webhook.event_types, webhook.event_field_mappings, webhook.event_processing_log, webhook.endpoints, webhook.event_mappings, webhook.validation_log, webhook.user_mappings (8 tables)
  • 9 internal functions

Dependencies: db.pg, db.ids, db.audit, db.auth.

Install rank: 6.


4. The core.* Layer (Structural Meta-Gnomons)

The core.* namespace is reserved for Tier 2 structural meta-gnomons (RFC-0049 ref kernel-primitives.md): kind-definitions, predicate-policies, modules, templates, entity-types, aspects, facets. These are gnomons ABOUT other gnomons.

4.1 core — bootstrap kinds

Purpose: the minimal set of kind-definitions that everything else builds on.

Owns PG schema: none (writes rows into graph.resource with kind <@ core).

Key declarations:

  • core.module — kind-definition for module gnomons
  • core.kind-definition — the kind that defines kinds (self-referential bootstrap)
  • core.predicate-policy — kind for predicate-policy gnomons
  • core.template — kind for template gnomons
  • core.template-args — kind for argument records (RFC-0050 §4.2)
  • core.transaction — kind for transaction gnomons (RFC-0050 §4)
  • core.principal — kind for principal gnomons (RFC-0048 §3.6)
  • core.session — kind for session gnomons
  • core.entity-type, core.aspect, core.facet, core.field-set, core.trait, core.view, core.action, core.operation, core.query, core.mutation, core.projection

Dependencies: db.graph (for table to write into).

Install rank: 7 (first non-db.* module).

4.2 core.kind — the kind machinery

Purpose: the registry and dispatch logic for kind-definitions.

Key declarations: validation pipeline, ltree-prefix matching, GiST index integration, kind-definition completeness checks.

Dependencies: core.

Install rank: 8.

4.3 core.policy — predicate-policy runtime

Purpose: the evaluator for predicate-policy rules (RFC-0042 §4.2).

Key declarations: the abstract evaluation contract; the bridge between Gnomon-level predicate-policies and PG-level RLS policy generation.

Dependencies: core, db.graph.

Install rank: 8.

4.4 core.template — template runtime

Purpose: the template instantiation runtime (RFC-0039 + RFC-0050).

Key declarations:

  • The template executor’s expected gnomon shapes
  • The provenance predicate registry (template.instance_of, template.with, template.instantiated_from, module.installed_by, principal.created_by, transaction.created_in)
  • The core.provenance(gnomonId) and core.lineage(gnomonId) projections (RFC-0050 §5)

Dependencies: core, db.graph.

Install rank: 8.

4.5 core.composition — aspect/facet/view runtime

Purpose: the aspect/facet composition algorithm (RFC-0004, kernel-primitives.md §Aspects and Facets).

Key declarations:

  • The aspect selector resolution
  • The facet ordering logic
  • The view rendering hooks
  • The extends protocol for module layering

Dependencies: core, core.kind.

Install rank: 8.


5. Application Modules

Application modules (savvi.*, ext.*, etc.) install on top of the platform layer. They:

  • Declare entity-types, predicates, predicate-policies, templates, queries, mutations, aspects, facets, views, actions.
  • Get a PG schema named after their namespace (e.g., savvi.studio.team → savvi_studio_team) for view-mapping outputs (RFC-0053).
  • Install through the normal RFC-0041 pipeline as the studio_app_connector role (or per-module subordinate role per KP28).
  • Cannot write to platform schemas directly; cannot extend core.* or db.*; cannot add to graph.reserved_namespaces.

Application module rank starts at 9 and orders by dependency closure.


6. Install Order DAG

Phase 1 (bootstrap.sql, frozen artifact):
  → extensions: ltree, pgcrypto, uuid-ossp, hstore
  → schemas: graph, audit, auth, ids, queries, webhook
  → owner roles
  → ids.gen_resource_id, ids.gen_statement_id
  → graph.resource, graph.statement (table only, plus basic RLS)
  → graph.predicate_policy, graph.reserved_namespaces
  → audit.events, audit.install_audit_trigger
  → bootstrap reserved namespaces (graph, core, db, gnomon)
  → system installer principal record

Phase 2 (normal install pipeline):
  rank 1:  db.pg
  rank 2:  db.ids
  rank 3:  db.audit
  rank 4:  db.graph (extends Phase-1 schema)
  rank 5:  db.auth, db.queries, db.util       (parallel)
  rank 6:  db.webhook
  rank 7:  core
  rank 8:  core.kind, core.policy, core.template, core.composition  (parallel)
  rank 9+: application modules (per dependency closure)

The install engine (RFC-0041 §4) computes the DAG from each manifest’s modules: dependency declarations. The ordering above is the deterministic result for the canonical platform set.

6.1 Bootstrap-to-pipeline transition

Phase 1 runs once at first DB initialization. Phase 2 runs every install (including the first). On a freshly bootstrapped DB:

  • db.pg, db.ids, db.audit install observe the Phase-1 state and install their non-bootstrapped artifacts (additional functions, full type catalogs, etc.).
  • db.graph install observes the Phase-1 graph tables and adds their full function set (the 88 functions cataloged in sql-ast-track-findings.md §6).
  • The fixed-point property holds: re-running the Phase-2 install on a Phase-1-bootstrapped DB produces an empty install plan after first install completes.

6.2 Cross-module dependencies (declarative)

Each platform module’s module.gnm MUST declare its modules: dependencies explicitly. The install engine validates the DAG; cycles are rejected (RFC-0041 §4.1, M41001).


7. The extends Protocol

Some platform modules layer on others without standalone PG schemas. For example:

  • core.graph.collection adds list/set semantics on top of core.graph — no new tables; just collection-aware kinds and predicates.
  • core.graph.traversal adds traversal-related entity-types — no new tables.
  • core.graph.policy adds policy-evaluation aspects.

These modules use the extends protocol declared in their manifest:

module core.graph.collection {
  namespace: core.graph.collection
  version:   1.0.0
  modules:
    - core
    - core.graph
  extends:
    core.graph:                           # this module extends core.graph's surface
      kinds: [collection.list, collection.set]
      predicates: [collection.item, collection.item-list-element, collection.position, collection.member]
}

The compiler validates that:

  1. The extended module is in the dependency closure.
  2. The extending module’s contributions don’t conflict with the extended module’s existing declarations.
  3. Cross-module template calls from an extending module to an extended module’s templates are permitted.

This is a generalization of the extends block already used by I/O adapters (RFC-0024 §6.2) — same mechanism, different application.


8. Cross-Module Template-Call Surface

Modules invoke each other’s templates via qualified template names:

core.template               # the canonical template-instantiation template
core.kind                   # register a kind-definition
core.predicate-policy       # register a predicate-policy
db.graph.resource-create    # platform-internal direct create (privileged)
db.audit.install            # install an audit trigger on a table
db.pg.table                 # declare a PG table from aspects
db.pg.function              # declare a PG function

These templates are exported (RFC-0040 §10) by their declaring module and consumed by callers via the templates: import list. Visibility rules (RFC-0039 §3.3) gate access:

  • Most platform templates are public — any module can use them.
  • Some are protected — only descendants of the declaring namespace can use them (e.g., db.graph.resource-create is protected; only db.graph.* and core.* can directly invoke it).
  • A few are private — only the declaring module uses them (internal helpers).

The protected and private visibility rules are how Architecture A (RFC-0036 alignment) enforces “Resource and Statement are intrinsics”: the db.graph.resource-create and db.graph.statement-create templates are protected to db.graph.* + core.*, blocking application modules from invoking them directly. Application code goes through core.template.instantiate which enforces template-mediated creation (RFC-0050).


9. The Migration from Legacy SQL

The legacy schema at db/migrations/000_initial_schema/*.sql already implements 92.5% of what these platform modules describe (per sql-ast-track-findings.md). The migration is:

PhaseWork
AGenerate .gnm for each db.* module from the legacy SQL via the existing reverse mapper (packages/sql-ast-analyzer/). 8 modules + 1 root.
BValidate the generated modules compile and produce DDL identical to the legacy via round-trip fingerprint test (Track D step D5).
CStop committing the legacy migration files; the compiled modules become the source of truth. The bootstrap.sql artifact is regenerated by RFC-0054 from the db.graph + db.ids + db.audit modules.
DLayer additional platform modules (core.kind, core.template, core.policy, core.composition) declaratively.

This is RFC-0054’s job (DDL Emission Pipeline) plus the existing reverse mapper’s output. This RFC catalogs the destination; RFC-0054 specifies the codegen.


10. Invariants

  1. The db.* and core.* namespaces are reserved; application modules MUST NOT declare modules in them (M52010).
  2. Each db.* module owns at most one PostgreSQL schema (§3); the schema name matches the module’s namespace (with . → _).
  3. The install order DAG (§6) is deterministic for the canonical platform set; future platform modules MUST declare dependencies that preserve the existing rank structure.
  4. Phase-1 bootstrap.sql + Phase-2 install produce the same end state as a from-scratch Phase-2 install on an empty DB; the fixed-point property holds (§6.1).
  5. The extends protocol (§7) is the only mechanism for adding to a platform module’s surface from another module; direct edits to platform modules’ objects from outside are prohibited (M52020).
  6. Platform module templates are visibility-gated (§8); db.graph.resource-create and db.graph.statement-create MUST be protected to enforce Architecture A (Resource/Statement as intrinsics).
  7. Application modules MUST NOT declare entity-types, predicates, or predicate-policies that resolve into core.* or db.* namespaces (M52030).
  8. The system installer principal (RFC-0048) is the only principal authorized to install platform modules; application module installs run as application principals.

11. Compatibility and Migration

11.1 From the legacy bootstrap

The legacy db/migrations/000_initial_schema/*.sql is the empirical equivalent of the catalog described here. The reverse mapper at packages/sql-ast-analyzer/ proves the mapping at 92.5% fidelity. The remaining 7.5% (imperative SET/DO/DROP statements) are operational scripts that don’t fit the declarative model and remain as one-off operator commands.

The migration produces no schema change — it changes the source-of-truth from .sql files to .gnm modules. The existing DB schema satisfies the modules described here.

11.2 Naming changes

This RFC’s db.* namespace supersedes my earlier proposal that used core.* for storage modules. The Q2 plan’s db.* is canonical. The core.* namespace is reserved for structural meta-gnomons only.

11.3 Layer additions (from the q2 plan and beyond)

The q2 plan’s kernel-primitives.md named only the foundational db.* modules. This RFC adds the core.* structural layer (§4), which has been implicit in the design but not previously cataloged.


Diagnostics

The diagnostic catalog for this RFC is authored in the structured Lean module and rendered in reference catalog § Diagnostics. Inline mentions in the prose above (e.g., “rejected with MNNxxx”) cross-link to the catalog at render time.

Linked References

The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.