gnomonlearn
Docs/RFC-0054/Reference catalog

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.

← Read the authored RFC

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

TermMeaning
Bootstrap lockfileThe committed bootstrap.sql artifact regenerated by this pipeline from db.graph + db.ids + db.audit.
DDL emissionThe compile-time step that transforms gnomon declarations into SQL DDL statements.
Declared stateThe schema implied by the compiled module bundle.
Destructive operationA DDL statement that destroys data: DROP TABLE, DROP COLUMN, ALTER TYPE with non-trivial cast, TRUNCATE.
Installed stateThe schema actually present in the target PostgreSQL database (or a snapshot thereof).
Plan diffDeterministic comparison: declared - installed = create/alter operations; installed - declared = drop operations.
Round-trip fingerprintSHA-256 of canonical-sorted SQL output; used to verify generation determinism and parity with an existing schema.

Diagnostics

CodeSeverityDescription
M54010ErrorInstall plan contains destructive operation(s) without explicit allow-destructive acknowledgment
M54011InfoDestructive operation in plan: on (one entry per destructive op)
M54020WarningDestructive operation removed an object before its two-phase deprecation grace period elapsed
M54030ErrorCodegen failed: declaration references undefined type, function, or schema
M54031ErrorCodegen failed: composed aspect contributes a column whose name conflicts with another aspect’s contribution
M54040ErrorPlan computation failed: declared state and installed state diff produces a cycle in the dependency DAG
M54041ErrorPlan computation failed: declared object’s qualified name collides with an installed object of a different category
M54050ErrorRound-trip fingerprint mismatch: generated SQL diverges from legacy SQL after canonicalization
M54060WarningDDL emission produced no output for module — module declares no schema-affecting artifacts
M54070ErrorFunction body asset (.sql file) referenced by db.pg.function declaration is missing or unreadable
M54071ErrorFunction body asset failed plpgsql parse validation (with libpg_query)
M54080WarningCross-module FK constraint declared; consider expressing as graph.statement relation instead
M54090Infobootstrap.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

  1. Cross-module DDL ordering respects manifest modules: dependencies. (enforced by: compile-time)
  2. Destructive operations require explicit acknowledgment before the install plan executes them. (enforced by: compile-time + CI)
  3. Stage 1 codegen output is bytewise deterministic for identical inputs. (enforced by: compile-time)
  4. The compiled bundle includes a ddl/ section with per-category SQL files and a ddl-fingerprint.json. (enforced by: compile-time)
  5. The migration-free model permits no db/migrations/ files in source — only .gnm modules and the generated bootstrap.sql lockfile. (enforced by: CI)
  6. The round-trip fingerprint test passes for the legacy schema after migration. (enforced by: CI)
  7. The two-phase deprecation lifecycle is the recommended path for removing user-facing objects. (enforced by: CI)
  8. View-mapping outputs flow through the same DDL emission pipeline as other categories. (enforced by: compile-time)
  9. 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

  1. MUST — CI MUST run the round-trip fingerprint test comparing generated SQL against canonicalized legacy SQL.

Cross-Module Dependencies in DDL

  1. 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)

  1. MUST — A plan with destructive ops without explicit acknowledgment MUST exit non-zero and emit M54010. (proof citation: rfc0054_b15_grounded; verification pending)
  2. MUST — CI MUST reject plans containing unacknowledged destructive operations. (proof citation: rfc0054_b17_grounded; verification pending)
  3. MUST — PRs intentionally including destructive ops MUST be tagged and reviewed by explicit signoff. (proof citation: rfc0054_destructive_ops_require_signoff; verification pending)

Determinism

  1. MUST — Determinism divergence MUST be reported with one of the failure-taxonomy codes (M0150-M0154). (proof citation: rfc0054_b13_grounded; verification pending)
  2. MUST — Two independent CI runs of the same module bundle MUST produce identical fingerprints.

Invariants

  1. MUST — Cross-module DDL ordering respects manifest modules: dependencies. (proof citation: rfc0054_cross_module_ddl_ordering; verification pending)
  2. MUST — Destructive operations require explicit acknowledgment.
  3. MUST — No db/migrations/ files in source — only .gnm modules and the generated bootstrap.sql lockfile. (proof citation: rfc0054_b11_grounded; verification pending)
  4. MUST — Per-module install transactions are atomic.
  5. MUST — Stage 1 codegen output is bytewise deterministic for identical inputs. (proof citation: rfc0054_b0_grounded; verification pending)
  6. MUST — bootstrap.sql is regenerated by CI and verified by diff. (proof citation: rfc0054_b7_grounded; verification pending)

Module SQL Artifact Layout

  1. MAY — Stage 3 apply MAY apply per-file or per-statement at operator discretion.

Linked References

DirectionTarget
Depends onRFC-0001
Depends onRFC-0002
Depends onRFC-0005
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-0041
Depends onRFC-0042
Depends onRFC-0048
Depends onRFC-0049
Depends onRFC-0051
Depends onRFC-0052
Depends onRFC-0053