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
| Term | Meaning |
|---|---|
| Platform module | A module in the db.* or core.* namespace that contributes to the runtime substrate. |
| Application module | Any non-platform module — savvi.*, ext.*, customer-namespaced modules. |
| Bootstrap module | A 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 module | A platform module that extends another via the extends protocol (RFC-0024 §6.2 generalized) — e.g., core.graph.collection extending core.graph. |
| Install rank | The 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.indexdb.pg.roledeclarations: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_configcomposite typeids.generator_metadatatableids.dns_label,ids.dns_name,ids.pg_identifier,ids.bit_countdomainsids.create_generator(name, config)functionids.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.eventstable (1 table)audit.install_audit_trigger(regclass)— adds trigger to a tableaudit.purge_old_events(before_timestamp)— retention helperaudit.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.resourceandgraph.statement(RFC-0051 §7.3) - SH1/SH2 triggers (RFC-0051 §7.4)
graph.collection_typeenum,graph.traversal_directionenumgraph.resource_input,graph.statement_inputcomposites
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 functionsauth.rotation_schedule_type,auth.key_type,auth.jwt_verify_resulttypes
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 gnomonscore.kind-definition— the kind that defines kinds (self-referential bootstrap)core.predicate-policy— kind for predicate-policy gnomonscore.template— kind for template gnomonscore.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 gnomonscore.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)andcore.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
extendsprotocol 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_connectorrole (or per-module subordinate role per KP28). - Cannot write to platform schemas directly; cannot extend
core.*ordb.*; cannot add tograph.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.auditinstall observe the Phase-1 state and install their non-bootstrapped artifacts (additional functions, full type catalogs, etc.).db.graphinstall observes the Phase-1 graph tables and adds their full function set (the 88 functions cataloged insql-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.collectionadds list/set semantics on top ofcore.graph— no new tables; just collection-aware kinds and predicates.core.graph.traversaladds traversal-related entity-types — no new tables.core.graph.policyadds 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:
- The extended module is in the dependency closure.
- The extending module’s contributions don’t conflict with the extended module’s existing declarations.
- 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-createis protected; onlydb.graph.*andcore.*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:
| Phase | Work |
|---|---|
| A | Generate .gnm for each db.* module from the legacy SQL via the existing reverse mapper (packages/sql-ast-analyzer/). 8 modules + 1 root. |
| B | Validate the generated modules compile and produce DDL identical to the legacy via round-trip fingerprint test (Track D step D5). |
| C | Stop 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. |
| D | Layer 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
- The
db.*andcore.*namespaces are reserved; application modules MUST NOT declare modules in them (M52010). - Each
db.*module owns at most one PostgreSQL schema (§3); the schema name matches the module’s namespace (with.→_). - The install order DAG (§6) is deterministic for the canonical platform set; future platform modules MUST declare dependencies that preserve the existing rank structure.
- 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).
- The
extendsprotocol (§7) is the only mechanism for adding to a platform module’s surface from another module; direct edits to platform modules’objectsfrom outside are prohibited (M52020). - Platform module templates are visibility-gated (§8);
db.graph.resource-createanddb.graph.statement-createMUST beprotectedto enforce Architecture A (Resource/Statement as intrinsics). - Application modules MUST NOT declare entity-types, predicates, or predicate-policies that resolve into
core.*ordb.*namespaces (M52030). - 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.