RFC-0054 · 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-0054: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0054.This page is generated from the
lean/Gnomon/Spec/module for RFC-0054. Edit that source and regenerate this catalog.
Title: DDL Emission Pipeline
Status: draft
Owners: Compiler, Storage
Diagnostic range: M54000-M54099
Depends on: RFC-0001, RFC-0002, 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, RFC-0053
Proof citations in source: 9 / 9. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| Bootstrap lockfile | The committed bootstrap.sql artifact regenerated by this pipeline from db.graph + db.ids + db.audit. |
| DDL emission | The compile-time step that transforms gnomon declarations into SQL DDL statements. |
| Declared state | The schema implied by the compiled module bundle. |
| Destructive operation | A DDL statement that destroys data: DROP TABLE, DROP COLUMN, ALTER TYPE with non-trivial cast, TRUNCATE. |
| Installed state | The schema actually present in the target PostgreSQL database (or a snapshot thereof). |
| Plan diff | Deterministic comparison: declared - installed = create/alter operations; installed - declared = drop operations. |
| Round-trip fingerprint | SHA-256 of canonical-sorted SQL output; used to verify generation determinism and parity with an existing schema. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M54010 | Error | Install plan contains destructive operation(s) without explicit allow-destructive acknowledgment |
M54011 | Info | Destructive operation in plan: |
M54020 | Warning | Destructive operation removed an object before its two-phase deprecation grace period elapsed |
M54030 | Error | Codegen failed: declaration references undefined type, function, or schema |
M54031 | Error | Codegen failed: composed aspect contributes a column whose name conflicts with another aspect’s contribution |
M54040 | Error | Plan computation failed: declared state and installed state diff produces a cycle in the dependency DAG |
M54041 | Error | Plan computation failed: declared object’s qualified name collides with an installed object of a different category |
M54050 | Error | Round-trip fingerprint mismatch: generated SQL diverges from legacy SQL after canonicalization |
M54060 | Warning | DDL emission produced no output for module — module declares no schema-affecting artifacts |
M54070 | Error | Function body asset (.sql file) referenced by db.pg.function declaration is missing or unreadable |
M54071 | Error | Function body asset failed plpgsql parse validation (with libpg_query) |
M54080 | Warning | Cross-module FK constraint declared; consider expressing as graph.statement relation instead |
M54090 | Info | bootstrap.sql regenerated; diff against committed file is empty or non-empty |
Dependency neighborhood
graph LR
nRFC_0054["RFC-0054"]
nRFC_0001["RFC-0001"]
nRFC_0054 --> nRFC_0001
nRFC_0002["RFC-0002"]
nRFC_0054 --> nRFC_0002
nRFC_0005["RFC-0005"]
nRFC_0054 --> nRFC_0005
nRFC_0006["RFC-0006"]
nRFC_0054 --> nRFC_0006
nRFC_0007["RFC-0007"]
nRFC_0054 --> nRFC_0007
nRFC_0008["RFC-0008"]
nRFC_0054 --> nRFC_0008
nRFC_0010["RFC-0010"]
nRFC_0054 --> nRFC_0010
nRFC_0024["RFC-0024"]
nRFC_0054 --> nRFC_0024
nRFC_0033["RFC-0033"]
nRFC_0054 --> nRFC_0033
nRFC_0036["RFC-0036"]
nRFC_0054 --> nRFC_0036
nRFC_0037["RFC-0037"]
nRFC_0054 --> nRFC_0037
nRFC_0038["RFC-0038"]
nRFC_0054 --> nRFC_0038
nRFC_0039["RFC-0039"]
nRFC_0054 --> nRFC_0039
nRFC_0040["RFC-0040"]
nRFC_0054 --> nRFC_0040
nRFC_0041["RFC-0041"]
nRFC_0054 --> nRFC_0041
nRFC_0042["RFC-0042"]
nRFC_0054 --> nRFC_0042
nRFC_0048["RFC-0048"]
nRFC_0054 --> nRFC_0048
nRFC_0049["RFC-0049"]
nRFC_0054 --> nRFC_0049
nRFC_0051["RFC-0051"]
nRFC_0054 --> nRFC_0051
nRFC_0052["RFC-0052"]
nRFC_0054 --> nRFC_0052
nRFC_0053["RFC-0053"]
nRFC_0054 --> nRFC_0053
Invariants
- Cross-module DDL ordering respects manifest modules: dependencies. (enforced by: compile-time)
- Destructive operations require explicit acknowledgment before the install plan executes them. (enforced by: compile-time + CI)
- Stage 1 codegen output is bytewise deterministic for identical inputs. (enforced by: compile-time)
- The compiled bundle includes a ddl/ section with per-category SQL files and a ddl-fingerprint.json. (enforced by: compile-time)
- The migration-free model permits no db/migrations/ files in source — only .gnm modules and the generated bootstrap.sql lockfile. (enforced by: CI)
- The round-trip fingerprint test passes for the legacy schema after migration. (enforced by: CI)
- The two-phase deprecation lifecycle is the recommended path for removing user-facing objects. (enforced by: CI)
- View-mapping outputs flow through the same DDL emission pipeline as other categories. (enforced by: compile-time)
- bootstrap.sql is regenerated by CI and verified by diff against the committed file. (enforced by: CI)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Compatibility and Migration
- MUST — CI MUST run the round-trip fingerprint test comparing generated SQL against canonicalized legacy SQL.
Cross-Module Dependencies in DDL
- SHOULD_NOT — Cross-module FK constraints SHOULD be avoided; use graph.statement relations instead. (proof citation:
rfc0054_cross_module_relations_are_edge_gnomons; verification pending)
Destructive Operation Gate (KP26)
- MUST — A plan with destructive ops without explicit acknowledgment MUST exit non-zero and emit M54010. (proof citation:
rfc0054_b15_grounded; verification pending) - MUST — CI MUST reject plans containing unacknowledged destructive operations. (proof citation:
rfc0054_b17_grounded; verification pending) - MUST — PRs intentionally including destructive ops MUST be tagged and reviewed by explicit signoff. (proof citation:
rfc0054_destructive_ops_require_signoff; verification pending)
Determinism
- MUST — Determinism divergence MUST be reported with one of the failure-taxonomy codes (M0150-M0154). (proof citation:
rfc0054_b13_grounded; verification pending) - MUST — Two independent CI runs of the same module bundle MUST produce identical fingerprints.
Invariants
- MUST — Cross-module DDL ordering respects manifest modules: dependencies. (proof citation:
rfc0054_cross_module_ddl_ordering; verification pending) - MUST — Destructive operations require explicit acknowledgment.
- MUST — No db/migrations/ files in source — only .gnm modules and the generated bootstrap.sql lockfile. (proof citation:
rfc0054_b11_grounded; verification pending) - MUST — Per-module install transactions are atomic.
- MUST — Stage 1 codegen output is bytewise deterministic for identical inputs. (proof citation:
rfc0054_b0_grounded; verification pending) - MUST — bootstrap.sql is regenerated by CI and verified by diff. (proof citation:
rfc0054_b7_grounded; verification pending)
Module SQL Artifact Layout
- MAY — Stage 3 apply MAY apply per-file or per-statement at operator discretion.
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0001 |
| Depends on | RFC-0002 |
| 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 |
| Depends on | RFC-0053 |